Go embed 匹配文件为空时怎样定位路径问题

Go 的 embed 匹配文件为空，最先要查的不是运行目录，而是 //go:embed 所在 Go 源文件的包目录。模式按这个包目录解析，不能用模块根目录、程序启动目录或编辑器工作区来猜路径；而且每个模式必须匹配至少一个文件或非空目录。官方资料入口：https://pkg.go.dev/embed。

先画出指令文件与资源目录的关系

假设项目布局如下，web/embed.go 和资源目录处在同一个包目录下：

demo/
├── go.mod
└── web/
    ├── embed.go
    └── assets/
        ├── index.html
        └── app.js

此时 web/embed.go 可以使用 assets/*，因为模式从 web/ 开始解析。若把指令放到项目根目录，却仍写 assets/*，就必须让根目录真的存在这个目录；把资源放在 web/assets 不会被自动递归猜到。模式不能用 ../ 逃出包目录，也不能指向另一个包含 go.mod 的独立模块。

通配符和目录模式不是同一件事

排查“明明有文件却匹配不到”时，重点看最后一级写法。目录模式会递归嵌入目录树，但以点号或下划线开头的文件默认排除；image/* 只匹配目录下一层的条目，能包含这一层的隐藏文件，但不会让更深层目录里的隐藏文件自动出现。若确实需要保留目录树中的隐藏或下划线文件，可使用 all:image，但要确认这些文件本来就应该进入二进制。

单个 string 或 []byte 变量只能绑定一个文件；需要多个文件或目录时使用 embed.FS。因此把目录通配符直接放到字符串变量上，也会得到与类型不匹配相关的编译错误，而不是“读取为空”。

用 embed.FS 把编译期和运行时拆开检查

下面的例子把资源目录嵌入文件系统，再用嵌入树中的相对路径读取。代码只展示接口关系；图片和示例输出均为说明用途，不代表本文执行过本地编译。

package web

import (
    "embed"
    "fmt"
)

//go:embed assets
var files embed.FS

// ReadIndex 从嵌入树读取 web 包目录下的 assets/index.html。
func ReadIndex() ([]byte, error) {
    data, err := files.ReadFile("assets/index.html")
    if err != nil {
        // 保留原始错误，便于区分路径写错与文件不存在。
        return nil, fmt.Errorf("读取嵌入首页: %w", err)
    }
    return data, nil
}

这里的 assets/index.html 不是操作系统当前目录下的路径，而是 embed.FS 内部的文件名。若改成 index.html，编译可能仍然成功，但运行时读取会失败，因为资源仍位于 assets/ 节点下。反过来，若 assets 不存在或是空目录，问题会在编译期暴露。

提交前按四层清单排查

我通常把排查固定成四层：第一层确认声明变量的包目录；第二层把模式展开成真实路径，检查大小写、文件名和目录是否提交；第三层确认隐藏文件规则与变量类型；第四层再看 ReadFile、Open 或模板解析使用的树内路径。这样不会把“编译时没收进去”和“运行时读错名字”混成一个问题。

如果项目用构建标签、生成脚本或多模块目录，还要在实际参与构建的源文件所在包里检查资源。不要在本机编辑器里新建了文件就认为 CI 一定能看到；忽略规则、大小写敏感性和生成时机都可能让目录状态不同。需要通配符时，优先用一个可读的目录结构，只有在确实需要保留隐藏配置时才扩大到 all:。

相关排查疑问

运行程序时切换工作目录会让 embed 失效吗？

不会改变编译期匹配结果。它可能影响你读取普通磁盘文件的代码，但嵌入文件已经成为程序内的只读文件系统；此时应检查 FS 内部路径。

为什么目录里有 .gitkeep 仍然像空目录？

以点号开头的文件默认不会被目录模式纳入。若只是为了让空目录进入版本库，不能把它当成业务资源；应提交真实文件，或明确评估是否使用 all:。

把模式写成绝对磁盘路径可以吗？

不行。embed 模式必须在包和模块允许的范围内使用相对路径；绝对路径既破坏可移植性，也不符合指令的路径规则。

定位顺序可以压缩成一句话：先找指令所属包，再展开模式看文件，最后核对嵌入树中的读取路径。官方实现和规则可继续查阅 https://go.dev/src/embed/embed.go 与 https://pkg.go.dev/io/fs。