精简说明:本包提供图片尺寸计算与压缩/转码策略;真实编码/解码能力由可选依赖 `sharp` 及其插件承担。只有在需要 **HEIC(HEIF) 支持** 时才要求执行 sharp 重建(使用系统 libvips 开启对应格式)。
npm install @stbzmi/common-node精简说明:本包提供图片尺寸计算与压缩/转码策略;真实编码/解码能力由可选依赖 sharp 及其插件承担。只有在需要 HEIC(HEIF) 支持 时才要求执行 sharp 重建(使用系统 libvips 开启对应格式)。
---
sharp 默认内置的 libvips 在部分平台不启用 HEIC/HEIF 支持。通过重建并链接系统安装的 libvips >= 8.17.3:不需要 HEIC 时可以直接使用预编译版本,跳过重建过程。
---
bash
pnpm add sharp sharp-bmp -F @stbzmi/common-node
`
未安装时仍可使用纯逻辑函数(尺寸/策略)。调用需要实际转码的 API 会给出缺依赖错误。---
快速重建指引
执行 monorepo 中的构建脚本以保证依赖准备;需要 HEIC 时再触发 sharp 重建:
`bash
pnpm build:shared # (按要求)先执行公共构建;确保基础类型/工具就绪
如果使用场景需要 HEIC:
node newTmm/scripts/rebuild-sharp.js --auto-install
`
说明:rebuild-sharp.js 会自动检测/安装缺失的 libvips、pkg-config 等,并清理预编译 @img 目录后源码编译。Windows 默认跳过(直接使用预编译)。---
环境最小要求
| 项 | 要求 | 目的 |
| -- | ---- | ---- |
| Node | >=20 | 与仓库统一,避免编译链差异 |
| libvips | >=8.17.3 | 启用 heif/webp/avif 支持 |
| 构建工具 | pkg-config, make, clang/gcc, python3 | sharp 编译依赖 |可选环境变量:
SHARP_FORCE_GLOBAL_LIBVIPS=1(强制使用系统 libvips)。---
常见问题速查
| 问题 | 解决 |
| ---- | ---- |
| 缺 pkg-config / vips | brew install vips pkg-config 后重跑脚本 |
| heif 仍不可用 | 确认 vips --version >= 8.17.3 且未加载内置 @img 目录 |
| ABI 报错 | 删除 node_modules 执行 pnpm install 再重建 |排查命令:
`bash
vips --version
file node_modules/sharp/build/Release/sharp.node
`---
与其他包
只提供图片策略与尺寸计算;上传/下载等由 @stbzmi/common-web 负责。无需图片转码时可不装 sharp。---
快速自检
`bash
node -v # >=20
vips --version # >=8.17.3 (需要 HEIC 时检查)
`---
更多背景与全量说明见根仓库
common/README.md`。