@stbzmi/common-node

精简说明：本包提供图片尺寸计算与压缩/转码策略；真实编码/解码能力由可选依赖 sharp 及其插件承担。只有在需要 HEIC(HEIF) 支持 时才要求执行 sharp 重建（使用系统 libvips 开启对应格式）。

为什么要重建 sharp

官方预编译 sharp 默认内置的 libvips 在部分平台不启用 HEIC/HEIF 支持。通过重建并链接系统安装的 libvips >= 8.17.3：

• 解锁 HEIC/HEIF 读取与转换。
• 统一 webp/avif/heif 等格式的处理能力，避免不同机器行为不一致。
• 降低后期升级到更高 libvips 时的阻力（无需等待官方重新发布预编译）。

不需要 HEIC 时可以直接使用预编译版本，跳过重建过程。

安装

按需安装原生依赖：

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

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

快速重建指引

执行 monorepo 中的构建脚本以保证依赖准备；需要 HEIC 时再触发 sharp 重建：

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 再重建 |

排查命令：

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。