模糊测试输入触发 panic 后的复现路径

Go 原生 fuzz 测试发现 panic 后，不要把它当成一次性随机事故。正确路径是先固定失败语料，再用 go test -run=FuzzXxx 重放，确认触发条件，修复输入边界，最后保留语料作为回归资产。Go 的 fuzz 引擎会把导致失败的输入写入该 fuzz 测试的 seed corpus；修复后，普通测试也会默认执行这些语料。

核心判断：-fuzz 负责继续搜索，-run 负责稳定重放。先让失败可重复，再讨论最小化和修复。

本文示例：一个解析函数直接读取 input[0]，空切片会触发 panic。示例只用于演示复现路径，图中内容均为原创静态说明图，不是运行截图。

步骤一：先确认 fuzz 失败点与测试函数

先从 fuzz 输出中记下测试函数名，例如 FuzzFrame，以及失败时的包目录。不要急着清理 testdata/fuzz，文件名中的哈希只是语料标识，真正有价值的是文件中的输入值。

func FuzzFrame(f *testing.F) {
	// 种子用于覆盖正常路径，模糊测试会继续变异它。
	f.Add([]byte("OK"))
	f.Fuzz(func(t *testing.T, input []byte) {
		// 这里调用待测解析函数，空输入是需要防守的边界。
		_ = firstByte(input)
	})
}

func firstByte(input []byte) byte {
	// 示例故意省略长度检查，用来演示 panic 语料如何产生。
	return input[0]
}

步骤二：用 -run 重放失败语料

拿到函数名后，先停止持续 fuzz，直接执行下面的命令：

# 只重放现有 corpus，不继续随机生成输入。
go test -run=FuzzFrame -v ./path/to/package

如果命令仍然在同一个 fuzz target 失败，说明问题已经脱离随机过程，具备稳定复现条件。若它通过，优先检查当前工作目录、包路径和语料目录是否对应，而不是立刻修改测试。

步骤三：读取并缩小输入边界

原生 fuzz 语料通常位于 testdata/fuzz/FuzzFrame/。文件内容会记录 Go 能还原的参数表达式，例如 []byte("...")。先查看内容，再把它翻译成问题边界：是空输入、长度不足、非法编码，还是字段组合不完整。

# 查看当前包中的失败语料，保留原文件作为回归输入。
find ./path/to/package/testdata/fuzz/FuzzFrame -type f -maxdepth 1 -print

# 读取某个语料文件；不要只看文件名哈希。
sed -n '1,20p' ./path/to/package/testdata/fuzz/FuzzFrame/

Go fuzz 在发现失败后会尝试缩小输入。即使生成的样本已经很短，也要用业务语言记录最小条件，例如“长度为 0 时访问第一个字节”，这样修复才不会只针对某个样本字符串。

步骤四：修复空输入或非法输入分支

修复重点不是捕获 panic，而是让输入契约在被测函数入口处变得明确。若 API 能返回错误，优先把非法输入转成 error；若函数签名不能改变，也至少返回安全的默认值，并在测试中覆盖边界。

func firstByte(input []byte) (byte, error) {
	// 先检查长度，避免非法输入越界访问。
	if len(input) == 0 {
		return 0, errors.New("empty frame")
	}
	// 只有通过边界检查后，读取首字节才是安全的。
	return input[0], nil
}

步骤五：回归运行并保留语料

修复后按“先固定、后探索”的顺序验证：

# 先确认历史失败语料已经不再触发 panic。
go test -run=FuzzFrame -v ./path/to/package

# 再用有限时长探索相邻输入，避免把本地命令变成长时间任务。
go test -fuzz=FuzzFrame -fuzztime=30s ./path/to/package

两条命令都通过后，不要删除 testdata/fuzz/FuzzFrame 下的样本。它既是 bug 的最小复现材料，也是未来改动的回归约束。若 fuzz 再找到新失败，仍然按同样路径记录 target、重放、解释边界，再决定是否需要扩展输入校验。

修复结果与边界

这套流程适合定位由输入内容触发的 panic、越界和非法格式分支；它不能替代竞态检测、超时测试或资源泄漏分析。-run 只验证当前已有语料，不能证明所有输入都安全；-fuzz 也不是一次性证明，而是带预算的持续探索。把 corpus 纳入版本控制，才能让修复结果在后续提交中持续可见。

常见问题

为什么不用重新启动 -fuzz 来复现？ 因为重新搜索会引入随机性和时间成本；已有失败语料用 -run 更快、更稳定。

失败语料文件名能说明问题吗？ 不能。哈希名用于区分 corpus 条目，必须读取文件内容并结合 target 的调用路径解释边界。