@stbzmi/common-node

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

---

为什么要重建 sharp

官方预编译 sharp 默认内置的 libvips 在部分平台不启用 HEIC/HEIF 支持。通过重建并链接系统安装的 libvips >= 8.17.3：
- 解锁 HEIC/HEIF 读取与转换。
- 统一 webp/avif/heif 等格式的处理能力，避免不同机器行为不一致。
- 降低后期升级到更高 libvips 时的阻力（无需等待官方重新发布预编译）。

不需要 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`。