Go embed pattern no matching files 怎样修复

我处理 go:embed 报 pattern ...: no matching files found 时，第一反应不应该是把通配符越改越宽，而是先问一句：这个模式是相对于哪一个目录解析的？它属于编译期匹配，基准是声明 //go:embed 的 Go 源文件所在包目录，不是启动程序时的当前工作目录。

官方资料：https://pkg.go.dev/embed

修复这类错误的核心顺序是：先定位声明文件和包目录，再核对模式实际能匹配到的文件，最后检查当前构建是否包含这份声明。运行时从哪个目录启动程序，只影响你用 os.Open 等 API 读取外部文件，不会改变已经写进二进制的嵌入资源。

先确认 pattern 到底相对于哪里解析

假设目录如下，server.go 位于 web 包目录中：

project/
├── go.mod
└── web/
    ├── server.go
    └── templates/
        ├── index.html
        └── admin.html

那么 server.go 中写 templates/*.html，匹配基准就是 project/web。写成 web/templates/*.html 反而会多走一层目录，通常得不到匹配。模式使用正斜杠，文件名大小写也必须和实际路径一致；Windows 上也不要把反斜杠当成 go:embed 模式分隔符。

最小写法可以这样组织：

package web

import "embed"

// templates 保存 web 包目录下 templates 中匹配到的模板文件。
//go:embed templates/*.html
var templates embed.FS

func hasTemplate(name string) bool {
    // 运行时只查询已经嵌入的 FS，不再依赖启动目录。
    _, err := templates.Open(name)
    return err == nil
}

如果变量类型是 string 或 []byte，模式还必须只匹配一个文件；需要一组文件时使用 embed.FS。另外，//go:embed 必须紧邻包级变量声明，中间只能有空行或普通行注释。

把“没有文件”拆成四种实际原因

报错文本相同，不代表修复动作相同。我会按下面四类检查，而不是直接改成 *：

1. 相对目录错了：模式是相对于声明文件所在包目录，不是项目根目录，也不是命令执行目录。
2. 模式没有命中：目录拼写、文件后缀、大小写或通配符写法不一致；一个空目录也不算可嵌入内容。
3. 资源不在允许范围：嵌入目标不能跑到模块外，也不能穿过另一个 go.mod 形成的独立模块边界；符号链接、vendor 等路径也不能用来绕过边界。
4. 声明文件没参与当前构建：文件顶部的 //go:build、文件名后缀或其他构建条件可能让这份 Go 文件在当前平台被排除。

修复时最好先把模式缩到一个确定存在的文件，确认路径关系后再恢复通配符：

package web

import _ "embed"

// 先用一个确定存在的文件定位包目录，确认后再扩展为目录模式。
//go:embed templates/index.html
var indexHTML []byte

如果单文件模式能通过，问题就集中在通配符、目录内容或文件名大小写；如果仍然失败，继续看声明文件是否参与构建和资源是否跨越模块边界。

不要用运行时工作目录解释编译期失败

下面两种代码都可能读取一个名为 assets/app.css 的文件，但它们解决的是不同问题：

• //go:embed assets/app.css：编译时把文件放进二进制，程序启动后不需要原始文件仍可读取。
• os.ReadFile("assets/app.css")：运行时按当前工作目录寻找外部文件，改变启动目录就可能失败。

package main

import (
    "embed"
    "fmt"
    "os"
)

//go:embed assets/app.css
var embeddedCSS embed.FS

func readEmbedded() ([]byte, error) {
    // 这个路径相对于嵌入 FS 的根，而不是进程当前工作目录。
    return embeddedCSS.ReadFile("assets/app.css")
}

func readExternal() ([]byte, error) {
    // 这个路径由启动程序时的工作目录解释，不能用来修复 go:embed 匹配失败。
    return os.ReadFile("assets/app.css")
}

func main() {
    css, err := readEmbedded()
    if err != nil {
        panic(fmt.Errorf("读取嵌入 CSS 失败: %w", err))
    }
    fmt.Println(len(css))
}

因此，看到“我在项目根目录执行命令还是找不到”时，不要继续切换 cd 位置。先回到声明 //go:embed 的那个包目录，按它的相对路径检查资源；只有使用 os.ReadFile 之类外部文件 API 时，当前工作目录才是首要线索。

构建文件是排查中的隐藏分支

“文件明明在目录里”仍报错时，重点看下面三项：

构建标签和文件名后缀

如果 embed_linux.go 或文件顶部的 //go:build linux 让声明只在 Linux 构建，当前在 macOS 或 Windows 执行时，这份声明文件可能根本没有进入包。此时你看到的路径存在，并不等于当前构建上下文能看到它。

模块根和嵌套 go.mod

go:embed 的匹配范围受模块边界约束。把资源放进另一个子模块、vendor 或模块外的目录，再用相对路径向上访问，不能当作合法修复。更稳妥的做法是把资源放在声明文件所属模块内，并让模式从该包目录向下匹配。

声明和变量的绑定关系

指令不能随意放在文件顶部或函数内部。它必须紧接着包级变量声明；如果中间插入其他声明，编译器会把它视为无效的 go:embed 用法，而不是普通文件查找问题。

用最小检查收集证据，不要盲目放宽模式

当目录看起来没问题时，可以用下面的方式确认当前包和嵌入字段。命令只是收集构建上下文，不会把运行时工作目录混进判断：

# 先确认当前模块和包位置，避免在错误的目录编辑文件。
go env GOMOD
go list -json ./web

# 只查看 Go 工具发现的嵌入模式和文件，不要先改成宽泛的通配符。
go list -json ./web | grep -E 'EmbedPatterns|EmbedFiles|Dir'

不同 Go 版本的 go list JSON 字段可能略有差异；如果看不到嵌入字段，先确认命令指向了包含声明文件的包，并检查当前构建条件。这里的检查结果用于定位“声明是否被看见”和“模式是否有候选”，不替代对模块边界的判断。

我会按这个顺序修复

1. 找到包含 //go:embed 的具体 .go 文件，确认它属于哪个包目录。
2. 从这个包目录出发，逐字符核对模式、文件后缀、大小写和目录是否为空。
3. 把模式临时缩成一个确定存在的文件，区分“相对目录错”与“通配符没命中”。
4. 检查 go.mod、嵌套模块、vendor、符号链接以及模块外路径。
5. 检查构建标签、文件名后缀和指令与包级变量的紧邻关系。
6. 只有确认嵌入成功后，才在运行时使用 embed.FS 的相对路径；不要再依赖进程当前工作目录。

一句话总结：pattern no matching files 首先是编译期文件匹配问题，解决它要看声明文件、包目录、模式和构建上下文；os.ReadFile 的工作目录问题属于另一条运行时路径，不能混在一起排查。

相关问题

为什么把 templates/*.html 改成 ./templates/*.html 仍然不行？

go:embed 模式不接受普通文件系统路径的任意写法，模式元素不能是 . 或 ..。从声明文件所在包目录直接写资源目录即可。

空目录为什么不能匹配？

目录模式需要至少能匹配到一个非空目录或文件。只有目录本身存在、里面没有可嵌入文件时，仍会被视为没有匹配结果。

可以把资源放在项目根目录再用 ../ 引用吗？

不可以。模式不能通过 .. 越过包目录，嵌入资源还必须处于允许的模块范围内。调整目录布局或把声明文件放到更合适的包中更可靠。

为什么程序换工作目录后，嵌入资源还能读取？

嵌入资源在构建时已经写入二进制，运行时通过 embed.FS 读取的是内置文件系统。只有改用外部文件 API 时，当前工作目录才会影响结果。