Go embed: pattern 没匹配到文件时怎么排查路径

Go 的 //go:embed 报“pattern 没有匹配到文件”时，先不要改 embed.FS 的读取代码。这个错误发生在编译期，优先检查声明指令所在的包目录、pattern 的相对写法、通配符是否真的覆盖文件，以及资源是否被放在了另一个 module 里。最有效的定位动作是用 go list 看 Go 工具链实际记录的 pattern 和匹配文件。

记住一条边界：//go:embed 的路径相对写在指令旁边的 Go 源文件所属包目录解析，不相对当前工作目录解析。先让每个 pattern 在编译期匹配到目标文件，再处理运行时的 ReadFile 路径。

先把 pattern 看成包目录下的匹配规则

假设项目结构如下，assets.go 和 web 目录属于同一个 assets 包：

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

对应写法是：

package assets

import (
    "embed"
    "fmt"
)

// 资源路径从本文件所属的 assets 包目录开始解释。
//go:embed web/*
var Files embed.FS

func ReadIndex() ([]byte, error) {
    // FS 内部路径仍然使用正斜杠，不带 assets/ 前缀。
    data, err := Files.ReadFile("web/index.html")
    if err != nil {
        return nil, fmt.Errorf("读取内嵌页面: %w", err)
    }
    return data, nil
}

常见误区是把路径写成 assets/web/*，因为开发者从 module 根目录看到了 assets；也有人写成 ./web/*、../assets/web/* 或 web\*。这些写法改变了 pattern 的语义，不能用“我从哪里执行 go build”来补救。文件名大小写也要完全一致，Linux 构建机不会替你容忍 macOS 上的大小写差异。

用 go list 查看实际匹配而不是猜

当路径看起来没问题但仍然编译失败，可以在包含该包的 module 中查看工具链记录：

# 查看包声明过的 embed pattern
go list -f '{{.EmbedPatterns}}' ./assets

# 查看 pattern 最终匹配到的文件
go list -f '{{.EmbedFiles}}' ./assets

第一条命令回答“代码里声明了什么”，第二条回答“这些声明最终命中了什么”。如果 EmbedPatterns 有 web/*.html，但预期的 index.html 不在 EmbedFiles，就检查文件层级、后缀和大小写；如果包路径本身加载失败，先确认当前目录仍在正确的 module 中。

* 是当前目录层的通配符，不会替你跨越任意目录。写目录名时，Go 会递归收集目录树中的文件，但默认忽略名称以 . 或 _ 开头的文件；空目录也不能单独提供有效匹配。每个 pattern 都必须至少匹配一个文件或非空目录，因此把可选资源目录直接写进指令，往往会在资源尚未提交时让构建立刻失败。

修正通配符后，再检查变量类型和运行时路径

如果变量类型是 string 或 []byte，指令只能使用一个 pattern，而且这个 pattern 只能匹配一个文件；需要装载多个模板或目录时，应使用 embed.FS。这不是把 string 改成 FS 就一定能解决，仍要确认 pattern 命中范围和读取路径。

编译期的 web/* 与运行时的 Files.ReadFile("web/index.html") 是两件事：前者决定哪些文件进入程序，后者使用 FS 内的相对名称查找。不要在 ReadFile 里再拼上 module 根目录或操作系统绝对路径，也不要把当前工作目录当成嵌入文件的根。

只有确实需要隐藏资源时才考虑 all:web。它会改变目录遍历时对点号和下划线文件的处理，但不能绕过模块边界、符号链接、非法文件名或“pattern 至少命中一项”的要求。发布前最好把资源目录作为源码的一部分检查，避免本地存在而 CI 未提交。

常见问题

pattern 能不能写成绝对路径？

不能按绝对路径思路使用。pattern 必须在声明文件所属包目录及其允许的子目录范围内解析，开头斜杠、.. 和跨 module 的路径都不适合用来定位资源。

为什么目录里明明有文件，pattern 仍然没匹配？

先看文件是否处在声明包目录下，再核对层级、大小写、后缀和名称是否以点号或下划线开头。用 go list 查看 EmbedFiles，比直接看编辑器文件树更准确。

读取时为什么还要写 web/index.html？

pattern 决定嵌入哪些文件，embed.FS 保存的是从包内路径开始的文件树。读取时要使用这棵 FS 中的相对路径，而不是 module 根目录的绝对路径。