故障排查

先保留完整错误文本、输入特征、实际版本和最小复现，再按症状进入对应路径。不要只凭进程 RSS、文件扩展名或一个导出参数判断根因。

按症状定位

安装与格式

处理链接、ABI、动态库和 unknown format 等问题。安装与 ABI · 缺少编解码器

访问顺序

复现 out of order read，区分顺序输入、随机操作和实体化修复。访问顺序错误

内存与并发

分开观察 ImageRef、Go 堆、libvips 缓存和 RSS，并检查并发所有权。疑似内存泄漏 · 并发崩溃

颜色与动画

排查 ICC、CMYK、偏色、帧丢失、page-height 和 GIF 编码参数。颜色偏移 · 动画与多页

保留能够触发问题的最小输入与完整调用参数，记录绑定和 libvips 版本，并把加载、变换和导出分开验证。只有在重复运行后仍能观察到同一信号，才把它写成稳定结论。

如果只记得错误消息或术语，可从术语、错误与资源索引反查页面；如果怀疑是版本差异，先检查版本兼容矩阵。