embed文件在测试包中找不到怎么办

在测试包里使用 //go:embed 找不到文件，先不要改当前工作目录。这个问题通常由两层路径混淆造成：嵌入模式是相对于声明它的 Go 文件所属包目录匹配，运行时读取 embed.FS 时又要相对于 FS 根传入路径。把测试资源放回包目录，并让读取路径与嵌入目录一致，通常就能解决。

最稳妥的组织方式是：在被测试包目录下放一个 testdata/ 或 fixtures/ 子目录，在测试文件中声明 //go:embed testdata/fixture.json，读取时继续使用 testdata/fixture.json，不要写成绝对路径或 ../testdata/fixture.json。

//go:embed 到底从哪里找文件

//go:embed 是编译期指令。它上面的变量声明必须紧邻指令，匹配模式按声明所在包的目录解释，而不是按你从哪个目录执行 go test 解释。测试文件叫 embed_test.go，并不会把这个规则改成“从项目根目录找”。

例如包目录是 profile，测试资源可以放在 profile/testdata/fixture.json。下面的模式匹配的是这个包目录下的文件：

package profile_test

import (
    "embed"
    "testing"
)

// testFiles 把资源编译进当前测试包，而不是在测试运行时读取磁盘。
//go:embed testdata/fixture.json
var testFiles embed.FS

func TestFixtureIsEmbedded(t *testing.T) {
    // 这里的路径相对于 testFiles 的 FS 根，使用正斜杠。
    data, err := testFiles.ReadFile("testdata/fixture.json")
    if err != nil {
        t.Fatalf("读取测试资源失败: %v", err)
    }
    if len(data) == 0 {
        t.Fatal("测试资源为空")
    }
}

如果 fixture.json 实际放在项目根目录，而测试包位于 internal/profile，就不能在指令中写 ../fixture.json 试图跨出去。嵌入模式不能用 .、.. 或空路径元素，也不能匹配包模块之外的文件。

把测试资源放到包目录内

排障时先按“测试包目录 + 本地资源目录”整理文件。testdata 是 Go 测试中常见的约定目录名，资源可以放在其中；也可以使用更明确的 fixtures。关键不是目录名，而是它必须位于声明 //go:embed 的包目录之下。

推荐的关系是：profile/embed_test.go 对应 profile/testdata/fixture.json。如果测试文件放在子目录 profile/contract，那它属于另一个包目录，匹配范围也随之变成 profile/contract，不能把父目录资源当作当前包的嵌入输入。

还要检查三处容易遗漏的细节：

• //go:embed 必须直接位于变量声明上方，中间只能有空行或普通行注释。
• 变量必须是字符串、字节切片、embed.FS 或其别名；使用 string / []byte 时，一个模式只能匹配一个文件。
• 即使只使用字符串或字节切片，也要导入 embed；不直接引用包名时使用空导入。

embed.FS 读取时路径又是另一层

文件成功嵌入后，读取失败仍然可能发生，因为 embed.FS 有自己的虚拟根。调用 ReadFile 或 fs.ReadFile 时，传入的是这个虚拟文件系统里的路径，而不是磁盘绝对路径，也不是进程当前工作目录下的相对路径。

package profile_test

import (
    "embed"
    "io/fs"
    "testing"
)

// testFS 的根就是包内资源被嵌入后的虚拟文件系统根。
//go:embed testdata/*
var testFS embed.FS

func readFixture(t *testing.T) []byte {
    t.Helper()

    // 路径从 FS 根开始，不能写成磁盘绝对路径或反斜杠路径。
    data, err := fs.ReadFile(testFS, "testdata/fixture.json")
    if err != nil {
        t.Fatalf("读取嵌入文件失败: %v", err)
    }
    return data
}

这里的 testdata/fixture.json 与指令中的目录前缀保持一致。如果改成 fixture.json，只有在变量直接嵌入单个文件且该文件位于 FS 根时才可能成立；如果使用了 testdata/*，目录名仍然是 FS 路径的一部分。

package 和 package_test 不会替你移动资源

同一个目录下，测试可以使用被测包本身的包名，也可以使用外部测试包名，例如 package profile 和 package profile_test。两者的可见性不同：外部测试包不能直接访问未导出的标识符，但它们仍然围绕当前包目录构建。

因此，遇到“换成 package profile_test 就找不到”的现象，要先检查三件事：

1. 测试文件是否真的和资源位于同一个包目录，而不是放进了另一个子目录。
2. 指令中的模式是否仍相对于该目录，例如 testdata/fixture.json，而不是项目根目录的想象路径。
3. 读取时是否把 FS 内路径误写成了操作系统路径，尤其是在 Windows 代码里混用了反斜杠。

如果资源只能由多个包共享，不要把一个包的 //go:embed 指令硬编码成跨目录读取。更清晰的做法是由资源所属包负责嵌入，再导出一个受控的 fs.FS 或读取函数；测试包只依赖这个公开接口。

构建标签和测试命令也会影响结果

当目录结构和路径都正确，却仍然出现“pattern matches no files”或测试代码里没有变量时，检查声明文件是否被当前构建条件排除了。带有构建标签的 _test.go 文件，只有在对应标签生效时才会进入测试构建；如果资源声明和调用被分到不同条件下，也会出现看起来像找不到文件的结果。

另外，go test ./... 会按包分别构建。命令从项目根目录执行，并不意味着每个包都可以引用根目录资源。先确认报错包的导入路径和本地目录，再回到该目录检查指令的相对路径。

# 先列出目标包的测试文件和包目录，避免在错误目录排查。
go list -json ./internal/profile

# 只运行当前包的测试，先排除 ./... 带来的其它包干扰。
go test ./internal/profile

# 需要构建标签时，在测试命令中显式传入同一个标签。
go test -tags=integration ./internal/profile

这些命令只帮助确认“当前测试包是谁、哪些构建条件生效”。它们不能把包外文件变成合法的嵌入输入；如果资源位置越界，仍应调整目录或由资源包提供公开访问接口。

最小回归：先确认编译期嵌入，再恢复业务断言

可以把业务测试暂时缩成一个文件存在性测试。只要它能通过，说明指令、包目录和 FS 路径已经对齐；随后再把 JSON 解码、模板渲染或业务断言加回去。

package profile_test

import (
    "embed"
    "io/fs"
    "testing"
)

//go:embed testdata/fixture.json
var fixtureFS embed.FS

func TestFixturePath(t *testing.T) {
    // 先验证嵌入后的路径是否存在，再测试文件内容。
    info, err := fs.Stat(fixtureFS, "testdata/fixture.json")
    if err != nil {
        t.Fatalf("测试资源未嵌入: %v", err)
    }
    if info.IsDir() {
        t.Fatal("测试资源路径指向目录")
    }
}

如果这个最小测试仍然失败，优先检查文件名大小写、资源是否为空目录、模式是否包含了 ..、声明是否被构建标签排除，以及测试文件是否真的属于预期包。不要先去改 os.Chdir 或拼接绝对路径，那只会掩盖编译期嵌入边界。

一张表记住排查顺序

常见追问

为什么把资源放在项目根目录，再用 ../ 就不行？

因为嵌入模式不允许用 . 或 .. 形成越界匹配，也不能跨出声明所在模块的合法包范围。应把资源放入使用它的包目录，或由独立资源包封装后提供接口。

测试运行目录变化会影响 embed.FS 吗？

不会影响已嵌入的文件内容；影响的是你自己用 os.ReadFile 读取磁盘时的相对路径。embed.FS 应始终使用自己的 FS 内部路径。

testdata 目录中的文件一定会被嵌入吗？

不会自动嵌入。必须有匹配它的 //go:embed 模式；同时以点或下划线开头的文件在普通目录匹配中有排除规则，需要时使用明确文件模式或支持隐藏文件的 all: 前缀。

最后记住一句：先定位声明文件属于哪个包，再确认嵌入模式能匹配到文件，最后按 embed.FS 根路径读取。这样排查时，工作目录、测试包名和资源路径就不会互相“背锅”。