嵌入目录中的隐藏文件为何没有进入二进制，匹配规则是什么

隐藏文件没有进入 Go 二进制，通常不是 embed.FS 读取失败，而是 //go:embed 的目录匹配规则主动过滤了它们：当模式直接命名一个目录时，该目录会递归嵌入，但任意层级中名称以 . 或 _ 开头的文件都会被排除。确实需要这些文件时，应使用 all: 前缀；只改成 目录/*，只能改变第一层的匹配效果，不能保证嵌套隐藏文件也被包含。

官方文档：https://pkg.go.dev/embed

排查这类问题时，我通常不会先怀疑构建缓存，而是先把“模式到底命中了什么”画出来。因为目录名、星号和 all: 看起来只差几个字符，实际表达的包含范围并不一样。

先确认是不是被目录规则过滤

假设资源目录如下。public.txt 和 nested/app.json 是普通文件，另外三个文件的名称分别以点号或下划线开头。

assets/
├── public.txt
├── .env
├── _draft.json
└── nested/
    ├── app.json
    └── .token

# 点号和下划线开头的名称会触发目录遍历的默认过滤规则。

如果声明写成下面这样，构建系统把 assets 当成一个目录递归遍历。结果中会有两个普通文件，但不会有 .env、_draft.json 和 nested/.token。

package resources

import "embed"

// files 嵌入 assets 目录，但目录遍历默认排除隐藏名称。
//go:embed assets
var files embed.FS

这项过滤不是操作系统的“隐藏属性”判断，而是文件名规则。即使在 Windows 上，只要某个路径元素以 . 或 _ 开头，目录模式也会将其排除；反过来，一个被系统标记为隐藏、但名称没有这两个前缀的文件，并不会因此自动被排除。

三种模式的包含范围并不相同

目录模式 assets：递归包含普通内容，同时在所有层级排除点号和下划线开头的名称。这是最保守、也最符合大多数静态资源场景的写法。

通配模式 assets/*：星号遵循 path.Match 的单层匹配语义，因此能直接匹配 assets/.env 和 assets/_draft.json。但星号也会匹配 assets/nested 这个目录；随后遍历这个目录时，默认过滤仍然存在，所以 nested/.token 不会因为外层用了星号就自动进入二进制。

all:assets：all: 会改变目录遍历规则，让名称以 . 或 _ 开头的文件也被包含。它是“完整保留目录树”的明确表达，而不是一个普通路径前缀。

package resources

import "embed"

// allFiles 明确包含 assets 树中的点号和下划线开头文件。
//go:embed all:assets
var allFiles embed.FS

我更倾向于先使用普通目录模式，只有当隐藏文件确实是运行时必需资源时才换成 all:。原因很实际：许多隐藏文件是编辑器配置、临时草稿、开发环境变量或工具元数据，把它们全部塞进二进制可能扩大产物，也可能把本不该发布的内容带进去。

用 WalkDir 看清二进制里实际有什么

如果代码打开文件时返回 fs.ErrNotExist，最有效的检查不是反复改相对路径，而是遍历 embed.FS。下面的辅助函数会打印已经进入嵌入文件系统的逻辑路径。

package resources

import (
    "fmt"
    "io/fs"
)

func PrintEmbeddedTree(fsys fs.FS) error {
    // 从逻辑根目录开始遍历，名称始终使用正斜杠。
    return fs.WalkDir(fsys, ".", func(path string, entry fs.DirEntry, err error) error {
        if err != nil {
            // 保留底层路径错误，便于定位无法读取的节点。
            return err
        }
        fmt.Println(path)
        return nil
    })
}

如果列表里根本没有目标文件，问题在构建期匹配；如果列表里存在，但 ReadFile 仍失败，才需要检查运行时代码使用的逻辑路径。嵌入路径相对于声明所在包目录，并且统一使用正斜杠，不能以斜杠开头或结尾，也不能包含空路径元素、. 或 ..。

data, err := allFiles.ReadFile("assets/nested/.token")
if err != nil {
    // 这里的路径是 embed.FS 内部逻辑路径，不是磁盘绝对路径。
    return fmt.Errorf("读取嵌入令牌文件失败: %w", err)
}
_ = data // 实际项目中应立即解析或交给只读配置层。

还有哪些内容不会进入嵌入文件系统

隐藏文件只是最常遇到的一种边界。官方规则还限制了模式的位置和可跨越范围：

• //go:embed 必须对应包级变量，不能放在函数内部；变量类型只能是字符串、字节切片或 embed.FS 及其别名。
• 模式相对于包含该指令的 Go 源文件所在包目录解释，分隔符始终是正斜杠。
• 模式不能越过当前模块边界，也不能匹配符号链接、.git、vendor/ 或包含另一个 go.mod 的目录。
• 空目录不会形成有效匹配；每条模式都必须至少匹配一个文件或非空目录，否则构建失败。
• 路径元素不能是 .、.. 或空字符串，模式也不能以斜杠开头或结尾。

这里有个容易混淆的地方：默认过滤隐藏文件时，构建可以成功，只是文件不在 embed.FS 中；而模式本身非法、越界或完全没有匹配时，构建会直接报错。一个是“成功构建但内容较少”，另一个是“构建不能完成”，排查方向并不相同。

怎么选择才不容易埋坑

对网页模板、前端静态文件和普通配置，我建议保留目录模式，让默认过滤帮助排除工具元数据。对确实需要的单个隐藏文件，可以显式写出该文件或使用足够窄的通配模式；只有整个目录树的隐藏内容都属于产品资源时，才使用 all:。

例如，真正需要的是一个公开的 .well-known 目录，就可以把范围控制在该目录，而不是把项目全部切换成 all:。选择模式时可以用三个观察点：

1. 目标文件是否真的属于随二进制发布的只读资源；
2. 使用 all: 后是否会额外包含开发配置、草稿或秘密文件；
3. CI 中能否通过一个小测试确认必需路径存在。

package resources_test

import (
    "testing"
    "testing/fstest"
)

func TestRequiredEmbeddedFiles(t *testing.T) {
    // 只声明运行时必需的路径，避免测试依赖整个目录列表。
    if err := fstest.TestFS(
        allFiles,
        "assets/public.txt",
        "assets/nested/.token",
    ); err != nil {
        t.Fatal(err)
    }
}

这个测试不会替你决定哪些隐藏文件应该发布，但能把“必需文件意外消失”变成构建阶段可见的问题。对我来说，这比把所有资源都宽泛地交给 all: 更容易长期维护。

几个相关问题

显式写 .env 会被过滤吗

点号文件可以被显式模式或直接匹配它的通配模式命中。是否应该嵌入是另一回事：真实环境变量文件往往含敏感配置，通常不应编译进二进制。更安全的做法是嵌入不含秘密的默认配置，再由部署环境覆盖。

assets/* 为什么仍然漏掉深层隐藏文件

因为星号只直接匹配当前层。它匹配到普通子目录后，子目录内部仍按目录遍历规则处理，深层的点号和下划线名称继续被排除。需要完整深层内容时使用 all:assets。

改了资源文件后为什么程序内容没变化

embed.FS 保存编译时快照。修改源文件后必须重新构建二进制，仅重启旧产物不会读取磁盘上的新内容。

归根结底，隐藏文件“消失”是匹配语义，而不是随机故障。先分清目录模式、直接通配和 all:，再用 WalkDir 观察实际嵌入树，通常几分钟就能把问题定位到构建期模式或运行时路径中的一边。