Go png.FormatError 怎么区分图片损坏和格式不支持

用 errors.As 匹配 png.FormatError 和 png.UnsupportedError，可以区分解码器报告的格式无效与不支持情形。但“不是 FormatError”不等于图片完好：截断、读取以及压缩数据错误可能返回其他类型。

官方地址：https://pkg.go.dev/image/png

为什么解码失败不能直接等同图片损坏

假设一个导入工具把所有 PNG 解码错误都显示为“图片损坏，请重新上传”。这个提示可能掩盖不同的处理方向：输入字节不符合格式时，应检查来源文件；当前解码器无法处理某种特性或尺寸范围时，应确认解码能力；文件没有读全时，则需要检查输入读取过程。

应先区分“没有解码成功”与“已经查明损坏原因”。类型能够给程序提供分类线索，却不能告诉程序文件是在下载、保存还是编辑时出了问题。扩展名为 .png 也不是字节格式有效的证明。面向用户的短提示和内部保留的原始错误，应当分别设计。

两类 PNG 错误分别说明什么

FormatError 是以 string 为底层类型的命名类型，表示输入不是有效 PNG。签名不正确、块顺序不符合要求、部分块长度不正确或校验和异常，都可能落到这一类。它带有 invalid format 前缀，但不应依靠搜索这段英文来分类。

UnsupportedError 的文档语义是输入使用了解码器尚未实现的 PNG 特性。实际处理还应结合具体消息：源码中维度溢出等无法表示的情况也使用这个类型。因此它更适合对应“当前解码能力或表示范围不支持”，不能一概承诺“升级版本就能打开”。

还有一个容易忽略的限制：解码器可能在检查完整份输入之前已经返回错误。遇到 UnsupportedError，并不意味着文件其他位置都已检查通过；把这个类型作为整个文件有效的证明，会扩大它的语义。

怎样用 errors.As 保留包装后的类型

下面是独立命令行示例。将代码保存为 main.go，在自己的 Go 工程中使用已有 PNG 文件路径作为参数。程序只读取和解码文件，不生成或修改图片；示例中的判断来自 API 语义，未把输出当作实际运行记录。

package main
import (
 "errors"
 "fmt"
 "image/png"
 "io"
 "os"
)
// kind 根据错误链分类，不重新读取文件。
func kind(err error) string {
 if err == nil { return "成功" }
 var format png.FormatError
 var unsupported png.UnsupportedError
 switch {
 case errors.As(err, &format):
  return "PNG 格式无效"
 case errors.As(err, &unsupported):
  return "PNG 解码能力或表示范围不支持"
 case errors.Is(err, io.ErrUnexpectedEOF), errors.Is(err, io.EOF):
  return "输入不足或读取提前结束"
 default:
  return "其他读取或解码错误"
 }
}
func inspect(path string) error {
 f, err := os.Open(path)
 if err != nil { return fmt.Errorf("打开图片: %w", err) }
 defer f.Close()
 _, err = png.Decode(f)
 if err != nil {
  // 使用 %w 包装，保留供调用方匹配的错误链。
  return fmt.Errorf("解码 PNG: %w", err)
 }
 return nil
}
func main() {
 if len(os.Args) != 2 {
  fmt.Fprintln(os.Stderr, "请提供一个 PNG 文件路径")
  os.Exit(2)
 }
 err := inspect(os.Args[1])
 if err != nil {
  fmt.Fprintf(os.Stderr, "%s：%v\n", kind(err), err)
  os.Exit(1)
 }
 fmt.Println("PNG 解码成功")
}

注意目标变量是 var format png.FormatError，然后传入它的地址。变量自身的类型是值类型 FormatError，不能习惯性改成 *png.FormatError；后者无法匹配标准库常见的值错误。UnsupportedError 也遵循相同写法。

普通类型断言只查看最外层动态类型。业务函数通过 fmt.Errorf 包装后，最外层已经改变，errors.As 才能沿链找回内部类型。包装使用 %w 保留这条关系；仅用 %v 拼成一段新错误文字，会失去可匹配的链。kind 负责短标签，日志同时保留 err 的具体信息。

截断和读取错误应该怎么处理

不要只写 FormatError 和 UnsupportedError 两个分支，再把 default 解释为“格式不支持”。PNG 解码还涉及 io.Reader 与压缩数据读取，异常可能来自这些层次。示例把 EOF 和 ErrUnexpectedEOF 单列为“输入不足或读取提前结束”，这是应用层展示分组，不是所有截断的固定错误类型。

同样是缺少末尾字节，实际错误还取决于缺失位置和解码路径。有的输入先触发格式检查，有的在读特定片段时发现提前结束，底层读取器也可能返回自己的错误。要进一步区分网络中断与磁盘问题，应在获取输入的一层保存上下文，而不是只从 PNG 错误猜测。

上例的 os.Open 失败进入“其他读取或解码错误”，原始详情仍有“打开图片”前缀。需要单列“文件打不开”的产品，可以在调用边界拆分业务状态。不要把文件不存在说成图片损坏，也不要在捕获错误后丢弃底层消息。

DecodeConfig 成功能证明文件完整吗

不能。DecodeConfig 用于读取颜色模型与尺寸等配置，不会完成整张图片的像素解码。配置可读，并不代表后续图像数据完整。如果任务是确定这次完整解码能否成功，就必须处理 Decode 的返回值。

先读配置再解码时，需要重新打开文件，或者把可定位读取器移回输入起点。不能把已消费一段的读取器直接交给 Decode，再把由此产生的报错归咎于原图。即便 Decode 成功，也只说明此次解码成功，不代表业务尺寸要求、所有元数据与来源可信度都已确认。

常见的类型判断疑问

JPEG 改成 .png 会返回 UnsupportedError 吗？

不能按后缀推断。png.Decode 面向 PNG 字节，完整的非 PNG 签名通常产生格式错误；输入短到不足以读取签名时，也可能先遇到读取错误。跨格式识别属于另外一层任务。

errors.Is(err, png.FormatError("")) 能识别全部格式错误吗？

不适合。FormatError 保存具体消息，不同消息是不同值。识别这一类类型使用 errors.As；识别 EOF 这样的已知错误值使用 errors.Is。

不支持时能直接重新编码吗？

应先确认是否有能够读取该输入的解码器。当前路径已经无法解码时，不能期待在同一失败路径上直接调用 Encode 就完成转换。保留具体错误，再根据实际能力决定后续处理。

相关资料：PNG 包文档、PNG 解码器实现、错误链匹配文档。