Go image.Decode 怎么根据文件头识别图片格式

很多上传接口会先看文件名的扩展名，再决定是否接受图片，但扩展名只是字符串，改名并不能改变文件内容。Go 的 image.Decode 会把输入当作 io.Reader，根据已注册解码器提供的文件头特征匹配格式，并返回图片、格式名和错误。也就是说，真正要读取格式时看第三个返回值里的 format，不要把 .jpg 当成事实。

最小写法是给需要支持的格式做空白导入，然后调用 image.Decode(reader)；它返回的格式名通常是 jpeg、png 或 gif。如果输入不可信，先用 image.DecodeConfig 检查宽高，再让 Reader 回到开头执行完整解码。

image.Decode 识别格式依赖什么

image.Decode 的签名是 Decode(r io.Reader) (Image, string, error)。第二个返回值就是注册时的格式名，函数不会从文件名、路径或上传字段中猜类型。标准库的 JPEG、PNG、GIF 解码器通常在各自包的初始化阶段注册，主包只需要空白导入：

package main

import (
    "fmt"
    "image"
    _ "image/gif"  // 注册 GIF 解码器，让 image.Decode 能识别 GIF 文件头
    _ "image/jpeg" // 注册 JPEG 解码器，让 image.Decode 能识别 JPEG 文件头
    _ "image/png"  // 注册 PNG 解码器，让 image.Decode 能识别 PNG 文件头
    "os"
)

func main() {
    file, err := os.Open("avatar.bin") // 扩展名故意不是图片扩展名
    if err != nil {
        panic(err) // 打开失败时不要继续把空句柄交给解码器
    }
    defer file.Close() // 文件句柄由当前函数统一释放

    _, format, err := image.Decode(file) // 根据文件头匹配已注册格式
    if err != nil {
        panic(err) // 未注册、格式损坏或内容不是图片都会到这里
    }
    fmt.Println(format) // 例如输出 jpeg，而不是 avatar.bin
}

注册关系可以理解成“解码器包提供识别规则，image.Decode 读取头部并返回名字”。image.RegisterFormat 接收格式名、magic 前缀、完整解码函数和配置解码函数；因此自定义格式也可以沿用同一套机制，但要自己承担注册和格式实现。

Reader 被消费后怎么继续读取

格式识别不是“只看一眼就不动 Reader”。解码器会从 Reader 读取数据；如果后面还要保存原文件、读取尺寸或再次解码，就必须考虑位置。文件通常实现 io.ReadSeeker，可以回到开头；HTTP body 这类流通常不能回退，应在大小受控的前提下先缓存。

func decodeWithLimit(r io.ReadSeeker) (image.Image, string, error) {
    const maxPixels int64 = 20_000_000 // 用像素数限制潜在内存开销

    cfg, format, err := image.DecodeConfig(r) // 先读头部，不申请完整像素缓冲区
    if err != nil {
        return nil, "", fmt.Errorf("read image header: %w", err)
    }
    if int64(cfg.Width)*int64(cfg.Height) > maxPixels {
        return nil, "", fmt.Errorf("image %s is too large", format) // 超限时拒绝完整解码
    }
    if _, err := r.Seek(0, io.SeekStart); err != nil { // 让完整解码重新从文件头开始
        return nil, "", fmt.Errorf("rewind image: %w", err)
    }
    img, format, err := image.Decode(r) // 同一份输入再次进入完整解码器
    if err != nil {
        return nil, "", fmt.Errorf("decode image: %w", err)
    }
    return img, format, nil
}

这里有两个容易混淆的边界：DecodeConfig 返回的是宽、高、颜色模型和格式名，不等于图片已经完整解码；Seek 只适用于可回退的 Reader。对网络上传内容，可以用 io.LimitReader 限制读取量后放进 bytes.Reader，再让探测和完整解码共享这份受控数据。

为什么会出现 image: unknown format

最常见原因是忘记空白导入对应的编解码包，或者输入的前缀并不属于已注册格式。比如只导入 image 而没有导入 image/png，即使文件确实是 PNG，也没有 PNG 解码器参与匹配。另一个常见情况是 Reader 已经被上游读过，当前游标落在文件头之后；对文件调用 Seek(0, io.SeekStart)，对缓存数据重新创建 bytes.NewReader(data)。

错误处理也不要只看格式字符串。只有 err == nil 时，返回的图片和格式才可使用；格式识别成功并不代表图片一定适合业务处理，尺寸、像素总量和后续转换仍需单独限制。对上传接口而言，建议把“字节数上限、头部尺寸上限、允许的 format 白名单”放在同一个入口处理。

常见问题

image.Decode 会根据 jpg、png 扩展名判断吗？

不会。它读取注册解码器定义的文件头特征，扩展名最多只能作为展示或初步筛选信息。

为什么 image.Decode 返回的格式是 jpeg 而不是 jpg？

格式名来自解码器注册时传入的名称，JPEG 解码器通常注册为 jpeg；业务判断应使用实际返回值或自己的映射表。

DecodeConfig 能代替 Decode 吗？

不能。它适合读取颜色模型、宽高和格式名并做资源门禁；需要像素数据时仍然要在 Reader 可读起点调用 image.Decode。

官方说明可继续查阅 image.Decode、image.RegisterFormat 和 image.DecodeConfig 的文档。