Go image.Decode 为什么在边界输入上得到空结果

Go 的 image.Decode 得到空结果时，先不要看文件名，直接检查返回的 img、format 和 err。最常见的原因是没有通过空白导入注册 PNG、JPEG 等解码器，或者 Reader 已经被前面的探测逻辑读到了末尾。格式未注册、输入为空、文件头不完整和图片确实没有像素，是四种不同情况，不能只用“图像为空”概括。

官方文档：https://pkg.go.dev/image

先把三个返回值一起看

image.Decode 返回 (image.Image, string, error)。第二个值是已注册解码器识别出的格式名；只要 err 非空，本次解码就不能当作成功。若调用方只判断 img == nil，很容易把“格式未知”与“输入为空”混为一谈。

package main

import (
	"bytes"
	"errors"
	"fmt"
	"image"
	_ "image/png" // 通过 init 注册 PNG 解码器，image.Decode 才能识别 PNG 文件头。
)

func decode(data []byte) {
	img, format, err := image.Decode(bytes.NewReader(data))
	if err != nil {
		// 错误优先于 img 和 format；格式未知时 format 可能仍是空字符串。
		fmt.Printf("decode failed: format=%q, err=%v\n", format, err)
		if errors.Is(err, image.ErrFormat) {
			fmt.Println("输入没有匹配到已注册的图片格式")
		}
		return
	}

	// 成功后再读取 Bounds，避免对 nil 图像继续调用方法。
	fmt.Printf("decode ok: format=%s, bounds=%v\n", format, img.Bounds())
}

func main() {
	decode(nil) // 空输入只用于演示错误分支，不代表一个有效图片。
}

这段代码把错误分支放在访问 Bounds 之前。空字节切片不会产生合法图像；即使解码器注册正确，也应保留并记录底层错误，而不是给 img 填一个默认图片继续向下传。

没有格式注册时，文件后缀也帮不了 Decode

image 包不会因为路径叫 photo.png 就自动加载 PNG 解码器。PNG、JPEG、GIF 等具体格式包通常在初始化时调用注册逻辑，因此常用做法是在导入区加入对应的空白导入：

import (
	"image"
	_ "image/jpeg" // 只注册 JPEG 解码器，导入本身不直接使用包名。
	_ "image/png"  // 只注册 PNG 解码器。
)

func readImage(r io.Reader) (image.Image, string, error) {
	// Decode 根据已经注册的格式签名识别数据，不根据文件扩展名猜测。
	return image.Decode(r)
}

上面的函数还需要把 io 加入导入列表；示例重点是空白导入的位置和作用。若程序只导入 image，遇到 PNG 或 JPEG 时通常会得到 image: unknown format，这不是图片像素为空，而是没有可用的格式解码器。

如果输入来自 GIF 或其他格式，也要导入对应的标准库格式包。若项目需要第三方格式，注册动作必须由该格式的官方解码包完成；不要通过修改文件名或手写后缀判断来伪装成已支持格式。

Reader 被读过以后，Decode 看到的可能只剩文件尾

很多“边界输入”并非图片坏了，而是同一个 Reader 先被 MIME 探测、哈希计算或日志预读消耗了一部分。image.Decode 从当前位置继续读，若当前位置已经在文件尾，就只能得到 EOF 或格式未知。调用前要明确 Reader 的所有权，以及是否能回到起点。

package main

import (
	"bytes"
	"fmt"
	"image"
	_ "image/png" // 让 image.Decode 具备 PNG 解码能力。
	"io"
)

func decodeAfterPeek(data []byte) error {
	r := bytes.NewReader(data)
	peek := make([]byte, 8)
	if _, err := io.ReadFull(r, peek); err != nil {
		return fmt.Errorf("读取文件头失败: %w", err)
	}

	// bytes.Reader 支持定位；回到零点后再交给解码器读取完整文件。
	if _, err := r.Seek(0, io.SeekStart); err != nil {
		return fmt.Errorf("重置读取位置失败: %w", err)
	}
	img, format, err := image.Decode(r)
	if err != nil {
		return fmt.Errorf("decode format=%q: %w", format, err)
	}
	if img == nil {
		return fmt.Errorf("解码器返回了 nil 图像")
	}
	return nil
}

若 Reader 不支持 Seek，可以把输入一次性读入 []byte，之后用新的 bytes.NewReader 交给不同阶段；也可以让预读阶段使用 io.TeeReader 同时保留副本。不要假定所有 io.Reader 都能回退。

不可信图片先读尺寸，再决定是否完整解码

格式已经注册、Reader 也在开头，仍然可能因为图片头声明了过大的宽高而出现内存压力。官方文档特别提醒，完整解码可能在所有像素都验证前按头部尺寸分配内存。处理上传或网络图片时，可以先用 image.DecodeConfig 读取配置，再设置面积上限。

package main

import (
	"fmt"
	"io"
	"image"
	_ "image/jpeg" // DecodeConfig 同样依赖具体格式包的注册。
	_ "image/png"
)

const maxPixels int64 = 20_000_000

func decodeWithLimit(r io.Reader) (image.Image, error) {
	conf, format, err := image.DecodeConfig(r)
	if err != nil {
		return nil, fmt.Errorf("读取 %s 配置失败: %w", format, err)
	}
	area := int64(conf.Width) * int64(conf.Height)
	if conf.Width  maxPixels {
		return nil, fmt.Errorf("图片尺寸不接受: %dx%d", conf.Width, conf.Height)
	}

	// DecodeConfig 已消费了 Reader；需要完整解码时应重新提供从头开始的 Reader。
	return nil, fmt.Errorf("示例只完成尺寸门槛判断，请用可回退输入重新 Decode")
}

这里故意没有把同一个不可回退的 r 直接传给 image.Decode。生产代码应保存原始字节，或使用支持 Seek 的输入，让配置读取和完整解码各自从文件头开始。

把“空结果”按原因分类处理

错误分类的价值在于让下游动作可控：格式注册问题不能靠重试解决，Reader 位置问题不能靠换文件名解决，尺寸问题也不应靠无限放宽内存上限解决。

几个容易误判的细节

只判断 format 是否为空可以吗？不可以。成功判断应以 err == nil 为主，同时确认 img 非 nil；format 是识别结果，不替代错误处理。

DecodeConfig 成功后可以直接 Decode 同一个网络流吗？通常不行。它已经消费了输入，除非 Reader 能 Seek 回到开始，否则需要缓存原始字节或重新获取输入。

为什么扩展名改成 png 仍然失败？image.Decode 看的是已注册格式的文件内容和魔数，不是路径扩展名。扩展名只能作为业务层提示，不能代替解码。

返回 nil 图像是不是一定代表图片损坏？不一定。先看 err、输入当前位置和是否注册格式；只有在解码器报告成功后仍出现不符合契约的 nil 返回，才需要进一步检查具体实现。

参考：image 官方文档、image/png 官方文档、image/jpeg 官方文档。