@stbzmi/common-node

精简说明：本包提供图片尺寸计算与压缩/转码策略；真实编码/解码能力由可选依赖 sharp 及其插件承担。Mac 平台使用预编译的 sharp（包含 HEIC 支持），Windows 平台使用官方预编译版本。

Sharp 预编译包

本包使用平台特定的 sharp 预编译包，避免本地重建：

• macOS Intel (x64): 使用 @stbzmi/sharp-darwin-x64（包含 HEIC 支持）
• macOS Apple Silicon (arm64): 使用 @stbzmi/sharp-darwin-arm64（包含 HEIC 支持）
• Windows (x64): 使用官方预编译版本（无需 HEIC 支持）

安装 common-node 时会自动根据平台选择对应的预编译包。

安装

按需安装原生依赖：

pnpm add sharp sharp-bmp -F @stbzmi/common-node

未安装时仍可使用纯逻辑函数（尺寸/策略）。调用需要实际转码的 API 会给出缺依赖错误。

预编译包构建说明

预编译包需要在对应平台的机器上构建：

macOS Intel (x64)

1. 在 Intel Mac 上安装依赖并重建 sharp：

   brew install vips pkg-config
   pnpm add [email protected]
   export SHARP_FORCE_GLOBAL_LIBVIPS=1
   export PKG_CONFIG_PATH=$(brew --prefix)/lib/pkgconfig:$PKG_CONFIG_PATH
   cd node_modules/sharp
   rm -rf node_modules/@img
   npm run build

2. 将构建产物复制到 packages/sharp-darwin-x64/prebuilt/：

   mkdir -p packages/sharp-darwin-x64/prebuilt/build/Release
   cp build/Release/*.node packages/sharp-darwin-x64/prebuilt/build/Release/

macOS Apple Silicon (arm64)

同上，但复制到 packages/sharp-darwin-arm64/prebuilt/。

Windows

无需特殊处理，使用官方预编译版本即可。

手动重建（备用方案）

如果预编译包不可用，可以手动运行重建脚本：

node scripts/rebuild-sharp.js --auto-install

说明：rebuild-sharp.js 会自动检测/安装缺失的 libvips、pkg-config 等，并清理预编译 @img 目录后源码编译。

环境最小要求

| 项 | 要求 | 目的 | | -- | ---- | ---- | | Node | >=20 | 与仓库统一，避免编译链差异 | | libvips | >=8.17.3 | 启用 heif/webp/avif 支持（Mac 平台） | | 构建工具 | pkg-config, make, clang/gcc, python3 | sharp 编译依赖（仅手动重建时需要） |

可选环境变量：SHARP_FORCE_GLOBAL_LIBVIPS=1（强制使用系统 libvips）。

常见问题速查

| 问题 | 解决 | | ---- | ---- | | 预编译包未找到 | 这是正常的，将使用官方预编译版本。如需 HEIC 支持，请手动运行重建脚本 | | heif 仍不可用 | 确认 vips --version >= 8.17.3 且未加载内置 @img 目录 | | Windows 平台 | 使用官方预编译版本，无需 HEIC 支持 | | ABI 报错 | 删除 node_modules 执行 pnpm install 再重建 |

排查命令：

vips --version
file node_modules/sharp/build/Release/sharp.node

与其他包

只提供图片策略与尺寸计算；上传/下载等由 @stbzmi/common-web 负责。无需图片转码时可不装 sharp。

快速自检

node -v              # >=20
vips --version       # >=8.17.3 (需要 HEIC 时检查)

更多背景与全量说明见根仓库 common/README.md。