Go embed 为什么提示 pattern 没有匹配文件

Go 编译时提示 pattern ...: no matching files found，最常见的原因不是文件“没有生成”，而是 //go:embed 后面的 pattern 没有在正确的包目录下匹配到它。先记住一句话：pattern 按声明它的 Go 源文件所在包目录解析，和你从哪个目录执行 go build 没有直接关系。

先确认 pattern 到底从哪里开始匹配

把 //go:embed 看成包内的静态资源声明更容易理解。源文件所在目录是解析起点，pattern 只能向当前包目录及其子目录寻找资源。下面这个布局中，main.go 与 web/index.html 属于同一个包目录的子树，因此 pattern 可以命中它：

project/
├── go.mod
├── main.go
└── web/
    └── index.html

如果资源实际位于 project/assets/，而声明文件位于 project/cmd/server/，就不能在 pattern 中写 ../assets 试图跨到包目录上方。此时要么把资源放到允许的包子树内，要么把嵌入声明放在能合法访问该资源的包中，再由业务包使用这个包暴露的变量。

四类路径问题会让文件看起来存在却匹配不到

定位这类错误时，不要先改成更宽的通配符。把实际资源路径和 pattern 放在同一张纸上逐项比较，通常很快就能找出差异。

还有一个容易忽略的因素是构建条件：如果资源目录或声明文件受 build tag、文件名后缀等条件影响，当前构建上下文可能并没有把你看到的那份文件纳入这个包。此时先确定参与当前构建的 Go 文件，再检查 //go:embed 所在声明是否就是你以为的那一份。

用最小声明还原正确的路径关系

下面示例把资源放在声明文件的子目录中，并使用一个明确的文件 pattern。[]byte 适合直接读取文本或二进制内容；如果后续要按文件名访问多份资源，则使用 embed.FS 更合适。

package main

import (
    _ "embed" // 让编译器启用 go:embed 指令。
    "fmt"
)

//go:embed web/index.html
var indexHTML []byte // pattern 相对当前包目录，匹配 web/index.html。

func main() {
    // 这里只展示读取已嵌入字节，不依赖运行时工作目录。
    fmt.Printf("embedded bytes: %d\n", len(indexHTML))
}

如果写成 //go:embed static/*.html，则必须确认 static 是声明文件所在包目录的子目录，并且至少存在一个符合通配符的可匹配文件。不要用“本地能看到目录”替代这项判断，因为资源是否在包边界内、文件名是否符合 pattern，都是编译期条件。

多文件场景可以改用 embed.FS：

package assets

import "embed"

//go:embed web/*
var Files embed.FS // 目录 pattern 把 web 下可匹配的资源放入文件系统。

func ReadIndex() ([]byte, error) {
    // 路径使用嵌入文件系统中的斜杠形式，不读取本机工作目录。
    return Files.ReadFile("web/index.html")
}

这里的 ReadFile 路径是嵌入文件系统里的逻辑路径，不是给 os.ReadFile 用的本机路径。若声明能编译但读取报文件不存在，应该继续检查 FS 内部路径是否带有 web/ 前缀，而不是回头修改磁盘目录。

把排查收敛成一张编译前清单

1. 找到真正包含 //go:embed 的 Go 文件，记录它所属包目录。
2. 从该目录拼出 pattern 的实际路径，确认没有依赖命令执行目录，也没有使用 ../ 跨包边界。
3. 逐字核对文件名、大小写和扩展名；通配符要确认至少有一个可匹配文件。
4. 若目录中只有点号或下划线开头的内容，按需要改为显式文件 pattern，或调整资源布局。
5. 检查 build tag、_test.go 等条件是否让你观察到的文件和当前构建包不一致。

最后再用项目自己的构建命令确认编译器能否接受这份声明。文章中的关键是“先确定 pattern 的解析根，再核对匹配集合”，而不是不断扩大通配符范围。这样即使项目从单包扩展到多个服务目录，资源声明的边界仍然清楚。

常见问题

pattern 可以写绝对路径吗？

不建议也不能把它当作任意文件读取接口。//go:embed 面向包内资源，pattern 应在允许的包目录及子树中解析，绝对路径和跨上级目录的写法都不是可靠解决方案。

为什么 static/* 还是匹配不到？

先看 static 是否相对声明文件位于正确位置，再看目录里是否只有不参与普通目录匹配的点号或下划线开头条目，以及当前构建是否使用了另一份带条件的声明文件。

应该用 []byte 还是 embed.FS？

单个文件、需要直接得到字节时用 []byte 更直观；多份模板、静态资源或需要按逻辑路径读取时用 embed.FS。两者都不能改变 pattern 的包目录边界。