Go embed 文件在测试包中为什么路径读不到

Go 测试包里用 //go:embed 读不到文件，通常不是测试运行时的当前目录造成的，而是把三个路径概念混在了一起：指令匹配路径相对声明它的包目录，embed.FS 读取的是嵌入树里的 slash 路径，只有仍在使用 os.ReadFile 时才需要关注进程工作目录。

测试资源规模一大，旧的相对路径写法先出问题

单个测试包只有一个夹具文件时，os.ReadFile("testdata/case.json") 看起来很省事；当测试被拆成多个包、改用外部测试包，或通过 go test ./... 批量执行后，当前目录假设就会变得脆弱。//go:embed 的价值在于把资源随测试程序一起编译进去，但它并不会把磁盘路径原样搬进程序。

建议先采用下面的目录关系，资源归属一眼可见：

config/
├── embed_test.go
└── testdata/
    └── case.json

指令和读取代码可以这样写：

package config

import (
	"embed"
	"testing"
)

// testFiles 把测试夹具绑定到 config 包，而不是绑定到运行时当前目录。
//go:embed testdata/case.json
var testFiles embed.FS

func TestCase(t *testing.T) {
	// ReadFile 使用嵌入树中的 slash 路径，不能写成磁盘绝对路径。
	data, err := testFiles.ReadFile("testdata/case.json")
	if err != nil {
		// 失败信息保留逻辑路径，便于区分模式错误和读取路径错误。
		t.Fatalf("读取嵌入夹具失败: %v", err)
	}
	if len(data) == 0 {
		t.Fatal("测试夹具为空")
	}
}

这里有两个关键点：//go:embed 的模式相对声明它的 Go 源文件所在包目录；ReadFile 的参数则相对嵌入文件系统根。把参数改成 ./testdata/case.json、/tmp/case.json 或项目绝对路径，都会偏离嵌入树中的名字。

先区分“没有匹配到”与“匹配到了但读错名”

第一类故障发生在编译测试时：模式没有匹配任何文件、含有不允许的 . 或 .. 路径，或者资源位于包目录之外。此时应修目录或模式，运行阶段还没开始。目录模式默认会递归嵌入，但名字以点号或下划线开头的文件会被排除；确实要包含它们时才考虑 all: 前缀。

第二类故障是编译通过后 ReadFile 返回 file does not exist。这往往说明文件已经被嵌入，只是读取名字写错。把模式写成 testdata/*.json 后，实际读取仍应保留 testdata/ 前缀；如果嵌入的是目录 fixtures，也不能默认把目录名删掉。

不要用运行时当前目录来修复第二类问题。当前目录只影响 os.ReadFile、相对配置文件和临时输出；embed.FS 是编译进测试二进制的只读文件系统，两者的根不同。

测试包变复杂时，用 go list 看资源到底归谁

同一个目录里可以同时有包内测试和外部测试包。测试文件中的嵌入模式也会按归属分别记录，排查时先执行：

# 查看当前包的测试嵌入模式和匹配文件，不依赖测试进程的工作目录。
go list -json .

关注输出中的 TestEmbedPatterns、TestEmbedFiles、XTestEmbedPatterns 和 XTestEmbedFiles。前两项对应包内的 package config 测试，后两项对应 package config_test 测试。若列表为空，先查文件是否在正确包目录、模式是否真的出现在 _test.go 中；若列表有文件，再逐字对照 ReadFile 参数。

把修复收敛成一个可回归的最小测试

多包项目里不要让每个测试自行猜路径。可以把夹具读取集中在包内的小函数中，让测试只接收字节或已解析对象；同时对缺失文件保留明确错误。提交前依次运行单包测试和全模块测试，确保目录移动、外部测试包切换以及并行执行时仍使用同一套嵌入名字。

# 先验证当前包，再覆盖模块中的其他测试包。
go test ./config
go test ./...

如果只有直接运行某个二进制或脚本时失败，检查它是否仍走 os.ReadFile。如果单包和全模块测试都在编译阶段失败，回到 go list 与目录结构，不要先改 chdir。这套分层能把问题从“路径读不到”缩小为一个具体边界。

常见问题

为什么 embed 不能读取项目根目录的文件？

嵌入模式受包和模块边界限制，不能把任意上级目录当作测试资源目录。把夹具移动到声明指令的包目录下，或由测试入口显式传入可测试的数据。

ReadFile 应该写文件名还是完整路径？

写嵌入树里的完整相对名字，例如 testdata/case.json。它不是操作系统路径，也不应带当前目录前缀。

什么时候才需要修改工作目录？

只有代码直接访问磁盘文件、配置或临时输出时才需要。已经使用 embed.FS 的读取逻辑，不应通过修改工作目录来补救。

官方资料可参考 https://pkg.go.dev/embed 与 https://pkg.go.dev/go/build：前者说明模式和嵌入文件系统，后者列出测试嵌入模式与文件字段。