版本兼容矩阵

本手册的“参考实现”是 Go/govips，锁定在固定版本。四个 binding 各自捆绑或链接的 libvips 并不相同，因此结果比较不能假定逐字节一致。

当前锁定的版本基线

角色	组件	版本	备注
参考	govips	v2.19.0	绑定到系统 libvips 8.17.3
参考	libvips	8.17.3	系统安装，与 pyvips、CLI 共用
比较	sharp	0.35.5	自带捆绑的 libvips 8.18.7
比较	pyvips	3.2.0	链接系统 libvips 8.17.3
比较	vips CLI	8.17.3	与参考共用系统 libvips

框架与运行时（可复现构建用）：Node 24、pnpm 12.11.2、Astro 7.3.8、Starlight 0.42.6、TypeScript 6.0.3、Go 1.27.0、Python 3.14.5。

为什么 sharp 版本不同

sharp 把编译好的 libvips 一并打包发布。因此 sharp 的 libvips 版本（8.18.7）与系统 libvips（8.17.3）不同，即使对相同输入编写相同意图的代码，sharp 与 govips/pyvips/CLI 的编码结果也可能存在合理差异。比较时不得假定逐字节一致。

pyvips 和 vips CLI 则链接系统 libvips 8.17.3，与参考实现共享同一个库，预期输出高度接近。

比较边界

• 当前比较策略是 metadata-only：验证尺寸、格式、通道、元数据等，不追求像素级一致。
• 像素级统一比较需要共享 libvips 基线的 runner，标注为 comparison-pending，尚未实现。
• 版本敏感结论必须写明具体的 libvips 与 binding 版本及复核日期，不要推广到所有版本。

何时需要升级

• 需要较新 libvips 才有的 op（见故障排查中 install-failures / missing-codec）。
• sharp 自带 libvips 与系统 libvips 的版本差导致行为差异时，应以锁定的参考基线为准。
• 升级任何 binding 或 libvips 后，请更新本矩阵并重新验证相关 Recipe。

来源

• 本仓库维护者锁定的 toolchain 基线（libvips 8.17.3、govips v2.19.0、sharp 0.35.5、pyvips 3.2.0、CLI 8.17.3）。
• govips README
• sharp versions（bundled libvips 8.18.7）
• pyvips
• libvips

本页为版本基线快照，复核日期 2026-10-11；升级后需重新验证。