Go image.Decode 报 unknown format 为什么需要空白导入

调用 image.Decode 读取 JPEG 或 PNG 时，如果返回 image: unknown format，通常不是文件名写错，而是对应的图像 codec 没有注册到 image 包。标准库的 JPEG、PNG 解码器会在各自包的 init 函数中调用 image.RegisterFormat，因此只想使用通用解码入口时，需要用空白导入把这个注册动作带进程序。

image.Decode 的格式表从哪里来

image.Decode 本身不是 JPEG 或 PNG 解码器，它只负责从已经注册的格式中寻找匹配项。每个格式注册信息包括名称、用于识别文件头的 magic 字符串，以及真正的 Decode 和 DecodeConfig 函数。找不到匹配项时，标准库返回 image.ErrFormat，错误文本就是 image: unknown format。

JPEG 和 PNG 包各自的 init 会注册格式。若代码只导入 image，codec 包没有进入依赖图，注册动作也就不会发生。空白导入正是为了解决这个依赖边界：

package main

import (
    "fmt"
    "image"
    "os"

    // 只为触发 image/jpeg 的 init 注册，不在代码中直接引用 jpeg 名称。
    _ "image/jpeg"
    // PNG 也需要显式注册，按实际输入格式保留或删除。
    _ "image/png"
)

func decodeFile(path string) error {
    // 打开文件后立即安排关闭，避免批量读取时泄漏文件描述符。
    f, err := os.Open(path)
    if err != nil {
        return err
    }
    defer f.Close()

    // Decode 会根据已注册格式的 magic header 选择解码器。
    img, format, err := image.Decode(f)
    if err != nil {
        return err
    }
    fmt.Printf("format=%s bounds=%v\\n", format, img.Bounds())
    return nil
}

这里的关键是副作用导入，而不是导入别名。若还要直接调用 jpeg.Decode，则应使用普通导入 "image/jpeg"；同一个包不能同时用两个导入声明，按实际调用方式选择即可。

空白导入与直接解码如何选择

有一个明确的判断标准：只支持一种格式就用专用解码器，需要在多种已注册格式之间自动识别才用 image.Decode。扩展名只能作为业务线索，真正参与识别的是文件头；把 photo.jpg 改名为 photo.png 不会改变内容。

package main

import (
    "fmt"
    "image"
    "io"
)

func inspect(r io.Reader) error {
    // DecodeConfig 只读取格式头部，用于先判断尺寸和颜色模型。
    cfg, format, err := image.DecodeConfig(r)
    if err != nil {
        return fmt.Errorf("读取图片头失败: %w", err)
    }
    // 这里的阈值是业务示例，生产环境应按内存预算配置。
    if cfg.Width  8000 || cfg.Height > 8000 {
        return fmt.Errorf("图片尺寸超出限制: %dx%d", cfg.Width, cfg.Height)
    }
    fmt.Printf("format=%s size=%dx%d\\n", format, cfg.Width, cfg.Height)
    return nil
}

要注意，DecodeConfig 和 Decode 都需要读取输入流。若底层是不可回退的网络流，先检查配置后还要重新获取流、使用可回读缓冲，或在设计上选择能同时满足检查与解码的读取方式。否则第二次读取可能已经错过文件头。

几个容易混淆的边界

• 导入成功不等于文件有效：空白导入只补齐格式注册，损坏或截断的图片仍可能在真正解码时失败。
• 支持范围由依赖决定：第三方格式也可以通过自己的 init 注册，是否支持要看对应 codec，而不是看文件后缀。
• 直接解码更明确：当业务已经从协议或字段确认格式时，专用 Decode 少一层自动识别，也更容易把错误定位到具体格式。

延伸问答

为什么只导入 image 仍然不能识别 PNG？

因为 image 提供的是通用接口和注册机制，不会自动加载所有 codec。需要额外空白导入 image/png。

空白导入会把图片解码吗？

不会。它只触发包初始化并登记格式，真正读取像素仍由 image.Decode 或专用 Decode 完成。

能不能只根据 .jpg 后缀选择解码器？

可以把后缀作为业务分流线索，但不要把它当作内容校验。可靠判断仍应检查文件头，并处理格式与后缀不一致的情况。