出现 unknown format 或缺少编解码器

image: unknown format 与 xxxsave not found 看起来都像“缺少格式支持”，但它们来自不同层。前者表示输入没有被当前检测路径识别；后者表示运行时 libvips 没有对应的加载或保存操作。

症状

加载/保存特定格式（JXL、BMP 等）报 image: unknown format。
gifsave buffer not found 或其它 save op 缺失。
加载 animated webp / animated avif 时报 unknown format，明明文件能打开。
BMP 想走 libvips，结果落到 Go 标准库兜底解码器。

先区分报错来自哪一层

1. govips 无法识别输入签名

govips 会先根据文件头识别 JPEG、PNG、GIF、TIFF、WebP、AVIF、HEIF、SVG、BMP、JPEG 2000、JPEG XL、PDF 等类型。输入过短、被截断、扩展名与内容不符，或当前 govips 版本尚未识别某个子格式时，DetermineImageType 会返回 ImageTypeUnknown。

govips v2.19.0 已在包内注册 Go 的 GIF、JPEG、PNG 与 WebP 解码器，其中 WebP 来自 golang.org/x/image/webp，不是 image/webp。仅仅为了使用 govips，应用不需要重复导入这些包。如果是应用自己的代码直接调用 image.Decode，才需要检查该代码路径是否注册了相应解码器。

先读取至少 12 字节并调用 DetermineImageType，再用 IsTypeSupported 检查当前运行时是否支持识别出的类型。不要只根据文件扩展名判断。

2. 运行时 libvips 缺少 loader 或 saver

gifsave_buffer not found、heifload not found 等错误表示当前运行时没有对应操作。原因可能是 libvips 版本过旧，也可能是构建时缺少 giflib、libheif、libjxl、PDF loader 等可选依赖；不能只靠升级 binding 判断。

用 vips --version 记录运行时版本，并通过 vips -l foreign 或 vips -l | grep -i <format> 检查实际注册的操作。容器构建阶段与生产运行阶段都要检查，避免编译镜像和运行镜像带有不同的 libvips。

3. 动图格式的类型检测漏识别

部分 govips 版本的类型检测函数（如 isAVIF）对 animated AVIF/WebP 识别不全，可能把有效动图判为 unknown format。先用 libvips CLI 验证文件能否加载，再在锁定的 govips 版本中复现；两者结果不同才更像 binding 侧的类型检测问题。

排查步骤

用十六进制工具或可信查看器确认输入不是空文件、截断文件或错误扩展名。
调用 DetermineImageType，记录 govips 判断出的类型。
调用 IsTypeSupported，并用 vips -l 核对运行时是否存在对应 loader/saver。
如果 CLI 能加载而 govips 不能，记录 govips、libvips 与依赖版本，再检查是否为已修复的类型检测缺陷。

受影响版本与边界

本页按 govips v2.19.0 源码复核；更早版本的内置识别规则和导入集合可能不同。
格式支持取决于运行时 libvips 的编译选项，不能从扩展名或 binding 版本单独推断。
应用自身直接使用 Go image 包时，解码器注册规则仍由该应用代码负责；这与 govips 内部已经完成的注册不是同一个问题。