格式与 Codec 支持矩阵

选择输入与输出格式前，先明确一个核心事实：读取取决于 libvips 编译时包含的加载器（loader），写出取决于原生编码器（native exporter）。 格式支持不是语言绑定（binding）自身的属性，而是底层运行时 libvips 的编译能力。

参考实现（libvips 8.17.3 / govips v2.19.0）的导出能力

govips ImageRef 提供以下 Export* 方法，代表 libvips 8.17.3 的原生写出支持（核对自 govips v2.19.0 源码）：

导出格式	方法
JPEG	ExportJpeg
PNG	ExportPng
WebP	ExportWebp
AVIF	ExportAvif
HEIF	ExportHeif
GIF	ExportGIF
TIFF	ExportTiff
JPEG 2000	ExportJp2k
JPEG XL	ExportJxl
其它（ImageMagick）	ExportMagick

读取支持与 Go 标准库回退边界

读取由 NewImageFromFile / LoadImageFromBuffer / LoadImageFromReader 按文件头签名分发给 libvips 编译进来的加载器。因此：

• 原生读取范围 = 当前运行时 libvips 编译时启用的 loader 集合（可通过 vips -l foreign 查看）。
• Go 标准库回退与内置注册：govips v2.19.0 已在包内自动注册了 Go 的 GIF、JPEG、PNG 与 golang.org/x/image/webp 解码器。应用仅仅为了使用 govips 不需要额外添加 _ "image/png" 等 side-effect import；只有当应用自身代码直接调用 Go 标准库 image.Decode 时，才需要自行管理解码器注册（详见出现 unknown format 或缺少编解码器）。
• 动图与子格式识别：部分旧版绑定对 animated AVIF 等子格式的文件头签名识别不全，排查时应先用 vips CLI 验证底层库能否打开。

常见格式速览

格式	读（参考基线）	写（参考基线）	备注
JPEG	支持	ExportJpeg	有损；支持 EXIF / ICC
PNG	支持	ExportPng	无损；支持 Alpha
WebP	支持	ExportWebp	有损/无损；支持动画与 Alpha
AVIF	支持	ExportAvif	有损/无损；动图签名识别在不同版本存在差异
HEIF/HEIC	支持	ExportHeif	依赖 libheif 编译配置
GIF	支持	ExportGIF	调色板格式；质量参数边界见 gif-quality
TIFF	支持	ExportTiff	支持多页
JPEG XL	支持	ExportJxl	取决于 libvips 是否编译 libjxl
JPEG 2000	支持	ExportJp2k	取决于 libvips 是否编译 OpenJPEG
PDF	读（pdfload）	经 magick/native	无专用 ExportPdf 方法
BMP	读为主	经 ExportMagick	无原生 loader 时可能走 Go 回退解码器

上表基于参考环境（libvips 8.17.3）；sharp 0.35.5 自带的 libvips 8.18.7 格式能力取决于其预构建配置，pyvips 与 CLI 则与系统 8.17.3 一致。其它入口的逐项格式对比标注为 comparison-pending。

关联排查页面

• 动图 / 多页：加载全部帧与拼接长图问题见动图只剩第一帧或变成纵向长图；GIF 编码参数见GIF 的 Quality 参数为何不生效。
• 色彩 / ICC：CMYK 缩放与 ICC 丢失见转换后偏色、ICC 丢失或 CMYK 失真。
• 未知格式与缺失 Codec：分层排查步骤见出现 unknown format 或缺少编解码器。

何时不适用

• 格式是否可用高度依赖目标机器或容器镜像中的 libvips 构建选项，不能仅凭本手册的快照推断。
• 不要仅因为参考环境支持某种格式导出，就假定其他入口或不同操作系统的发行版默认启用了相同的编解码器。

来源

• govips v2.19.0 源码（image_export.go、image.go、foreign.go）。
• 本手册故障排查章节：missing-codec、animation-multi-page、gif-quality、colour-shift。

本页为版本快照，复核日期 2026-10-12；格式支持随运行时 libvips 构建配置而变化。