Go embed 的 glob 没匹配文件时为什么构建直接失败

Go 的 //go:embed 并不是“找不到文件就跳过”的可选复制操作。只要 glob 模式没有匹配到文件或非空目录，构建阶段就会失败。最直接的处理顺序是：先确认报错对应的模式，再以 //go:embed 所在 Go 源文件的包目录为起点检查路径，最后决定是补上资源、修正 glob，还是改成适合单文件的变量声明。

“no matching files found”说明输入集合为空，而不是 embed.FS 读取失败。先修正编译期匹配关系，再谈运行时的 ReadFile。

先把“无匹配”与运行时读取区分开

例如源文件位于 internal/web/assets.go，写了下面的模式：

package web

import "embed"

// 静态资源在编译期一次性收集到只读文件系统。
//go:embed templates/*.html
var templates embed.FS

如果 internal/web/templates 不存在，或者目录存在但没有任何以 .html 结尾的文件，go build 会在解析指令时直接报 pattern templates/*.html: no matching files found。此时程序还没有启动，templates.ReadFile 的错误处理并不能修复问题。

按 Go 源文件的包目录重新计算相对路径

最常见的误判是把 glob 当成“从项目根目录开始”。实际上，模式相对包含这条指令的 Go 源文件所在包目录解释，路径分隔符使用正斜杠。下面这个树形关系可以帮助快速定位：

project/
├── go.mod
└── internal/web/
    ├── assets.go          //go:embed 在这里
    └── templates/
        └── home.html

上面的 assets.go 应使用 templates/*.html，而不是 internal/web/templates/*.html。后一个模式会从 internal/web 再向下寻找同名层级，自然匹配不到。排查时同时检查三点：文件名大小写是否完全一致、通配符后缀是否写错、资源是否被移动到了包含另一个 go.mod 的嵌套模块。

根据资源意图选择三种修复方式

不要为了让构建通过而盲目把模式改成 *。先判断这个资源是否应该存在。

• 资源是必需品：创建或恢复目标文件，并把它加入提交清单。模板、默认配置和前端入口通常属于这一类。
• 路径层级写错：保留文件树不变，只修正相对包目录的 glob；不要用工作目录变化掩盖源代码中的路径错误。
• 资源是一个目录集合：让模式指向真实的非空目录，或使用 all: 前缀明确表示还要包含以点号或下划线开头的文件。

如果只想嵌入一个确定文件，可以让变量使用 string 或 []byte，此时模式必须只匹配一个文件；多个文件或目录树才使用 embed.FS。不要把一个可能匹配多个文件的 glob 直接绑定到字符串变量。

package config

import _ "embed"

// 单文件模式只能得到一个明确文件，适合固定模板或版本标记。
//go:embed defaults.json
var defaults []byte

用 go list 和 go build 做最小复查

修正后先不要急着启动完整服务。用 go list 查看 Go 工具识别到的嵌入模式，再运行构建：

# 在模块根目录执行，先看工具记录的嵌入模式。
go list -json ./internal/web | grep -A3 -E 'EmbedPatterns|TestEmbedPatterns'

# 再执行真实构建；空匹配仍会在这里暴露。
go build ./internal/web

如果构建已经通过，再验证运行时路径。embed.FS 里的名字通常相对嵌入根目录，例如上例可以读取 templates/home.html，而不是本机绝对路径：

package web

import (
    "embed"
    "fmt"
)

// 读取路径必须使用嵌入文件系统中的相对名称。
//go:embed templates/*.html
var templates embed.FS

func loadHome() error {
    data, err := templates.ReadFile("templates/home.html")
    if err != nil {
        // 运行时只处理读取错误，编译期 glob 问题应在 build 前解决。
        return err
    }
    fmt.Println(len(data))
    return nil
}

常见问题

空目录为什么也会触发构建失败？

glob 需要至少匹配一个文件或非空目录。只有目录本身存在、但里面没有可匹配资源时，输入集合仍然为空；应补入真实资源，或删除这条不再需要的嵌入指令。

改成 * 就能解决所有问题吗？

不能。* 可能扩大资源范围，并且仍然要求至少有匹配项。它只适合表达“当前包目录下的一组资源”，不适合掩盖目录层级写错。

为什么本地能过，CI 却提示没有匹配文件？

通常是资源没有提交、大小写在不同文件系统上表现不同，或者 CI 使用了不同的包路径。先查看版本库中的真实文件名，再从包含 //go:embed 的包目录重新计算模式。

归根结底，//go:embed 的 glob 是构建输入契约：模式、包目录和资源清单必须同时成立。把错误定位在这个契约上，通常比在运行时反复捕获文件读取错误更快。