安装、链接与 ABI 不匹配

如果错误发生在编译、链接或程序启动阶段，先不要从图像处理逻辑入手。第一步是确认编译器看到了哪个 libvips，以及程序运行时实际加载了哪个动态库。

症状

Wrong JPEG library version：编译期链接的 libjpeg 与运行时实际加载的版本冲突。
链接到了错误的 libvips（系统中安装多个版本时）。
新版 libvips 才有的 op（如 gifsave / heifsave）在相对旧的库上 not found。
M1/交叉编译时缺失特定符号，或链接阶段找不到平台相关的 ABI 定义。

排查思路

1. 确认链接到哪个库

先确认使用的 govips 版本（如 go list -m -f '{{.Version}}' github.com/davidbyttow/govips/v2），再用 ldd 确认最终链接的 libvips 与 libjpeg 的实际路径和版本。

# 示例：查看可执行文件实际链接的动态库
ldd ./your-binary | grep -iE 'vips|jpe?g'

版本敏感结论应写明是哪个 libvips / govips 版本、复核日期，不要把“某版本能跑”推广为所有版本通用。

2. 区分两类错误

编译期缺失符号：#cgo 或链接阶段找不到符号，通常是 cgo 的 include/library 路径、或交叉编译工具链问题。
运行时库不匹配：能编译但启动/运行报版本错误（如 libjpeg 版本冲突），通常是 LD_LIBRARY_PATH、动态链接缓存或系统里多个互斥版本导致。

两者排查方向不同，先判定属于哪一类。

3. 版本门槛操作

gifsave、heifsave 等操作依赖较新的 libvips；not found 或 image too large 往往说明运行时 libvips 比编译时旧。统一编译期与运行期的 libvips 版本，能消除这类“能编译不能运行”的怪异。

4. 交叉编译注意

M1 / 交叉编译环境容易因缺少目标平台的平台符号或 ABI 定义而链接失败。需要安装对应平台的依赖库并在 #cgo 指定正确的交叉链接参数。

受影响版本与边界

编译期与运行期都已对齐、链接正确的库——此时报错通常是别的问题。
ABI 匹配但功能参数（如某 op 的边界）不同——这是不同版本行为，不是安装故障。
本页以 govips v2.19.0 与 libvips 8.17.3 为当前复核基线；macOS、Linux 与容器镜像需要使用各自的动态库检查工具。

来源

版本与 ABI 行为高度依赖具体构建环境；结论应以目标系统实际加载的 libvips 与依赖库为准。