Go go tool covdata merge 怎样合并多次覆盖率数据

如果同一个 Go 集成测试程序分别在 Linux、macOS 或不同测试场景运行，覆盖率数据通常会落在多个 GOCOVERDIR 目录中。直接对其中一个目录执行报告命令，会漏掉其它运行结果。正确做法是用 go tool covdata merge 把这些目录合并到新的输出目录，再对合并结果执行 percent 或 textfmt。

官方地址：https://go.dev/cmd/covdata

合并的输入是覆盖率数据目录，不是 go test -coverprofile 生成的文本文件；每个输入目录通常包含一个 covmeta.* 元数据文件和一个或多个 covcounters.* 计数文件。

先看懂 covdata merge 合并的对象

使用 go build -cover 构建的程序在运行时把覆盖率数据写入 GOCOVERDIR 指定的目录。元数据描述源文件、函数和插桩布局，计数文件记录这一次运行实际命中的代码区域。多次运行通常共享同一份元数据，但会产生不同的计数文件。

因此，合并命令的核心不是拼接文本，而是读取每个目录中的二进制元数据和计数，再按覆盖率工具的规则生成一组新的数据文件。输出目录最好新建，避免把输入目录当成输出目录。

用 -i 和 -o 合并多个目录

假设两个平台分别把数据写入 cov-linux 和 cov-macos，可以这样合并：

# -i 接收逗号分隔的覆盖率数据目录，-o 指定新的输出目录
go tool covdata merge -i=cov-linux,cov-macos -o=cov-merged

# 对合并后的原生数据输出每个包的语句覆盖率
go tool covdata percent -i=cov-merged

# 如需兼容传统工具，再转换成文本覆盖率格式
go tool covdata textfmt -i=cov-merged -o=coverage.txt

-i 是逗号分隔的目录列表，不是文件列表；-o 是合并结果目录。命令成功后，后续报告命令都应指向 cov-merged，而不是某个单独平台目录。

输入目录怎样准备才不会漏数据

每次运行前给不同场景使用不同的目录，尤其是并行测试或跨平台测试。这样既能保留原始数据，也能在合并失败时定位是哪一组输入有问题。

# 先构建带覆盖率插桩的集成测试程序
go build -cover -o app ./cmd/app

# Linux 场景把运行结果写到独立目录
mkdir -p cov-linux
GOCOVERDIR=cov-linux ./app -scenario=linux

# 另一个场景使用另一个目录，避免覆盖原始计数文件
mkdir -p cov-smoke
GOCOVERDIR=cov-smoke ./app -scenario=smoke

如果没有设置 GOCOVERDIR，插桩程序仍可能正常运行，但不会写出完整的覆盖率数据。合并前应确认输入目录确实来自同一个覆盖率采集链路，并保留原始目录作为可追溯的输入。

合并后怎样生成统一报告

最直接的是查看语句覆盖率：

# 输出合并数据中每个已插桩包的覆盖率
go tool covdata percent -i=cov-merged

# 只关注某个模块路径，减少大型仓库的噪声
go tool covdata percent -i=cov-merged -pkg=example.com/project/internal/parser

如果流水线仍然消费传统的覆盖率文本，可以使用 textfmt 转换。注意：文本转换是报告格式转换，不是再次合并；合并动作应在二进制原生数据目录阶段完成。

三个容易误判的边界

尤其不要把 covdata merge 当作任意覆盖率文件的通用拼接器。它面向 Go 二代覆盖率输出；如果手里已经是 go test -coverprofile 的文本文件，应使用适合文本格式的工具链，而不是把文本路径塞给 -i。

常见问题

为什么 merge 后覆盖率没有简单相加？

覆盖率是按插桩单元的命中状态汇总，不是把两个百分比做算术相加。多次运行命中同一语句时，合并结果仍然只代表它被覆盖。

多个输入目录必须来自同一台机器吗？

不必。跨平台合并正是常见场景，但输入需要来自可兼容的覆盖率插桩数据；平台差异不等于可以合并任意两个不同程序的元数据。

什么时候使用 -pkg？

当仓库包含大量被插桩包、报告噪声太大时，用 -pkg 选择要报告的导入路径。它改变报告筛选范围，不改变已经写入的合并数据。

记住一条顺序即可：各场景独立设置 GOCOVERDIR，用 go tool covdata merge -i=... -o=... 汇总，再对新目录执行 percent 或 textfmt。这样能同时保留原始证据和统一报告。