Go embed 目录模式匹配不到隐藏文件时怎么处理

用 //go:embed 打包静态目录时，普通文件能读到，.env.example、_draft.json 这类文件却不见了，通常不是文件权限问题，而是匹配规则的默认行为：目录递归会排除名称以点号或下划线开头的文件。需要递归保留它们时，把模式写成 all:目录，例如 //go:embed all:assets。

Go embed 为什么会跳过隐藏文件

embed 的目录规则是有意设计的。目录可能包含编辑器临时文件、版本控制目录或开发机配置，编译时默认把名称以 . 或 _ 开头的文件排除，避免它们被意外打进最终二进制。这里的“隐藏”按名称判断，不是按操作系统权限判断；在 Linux、macOS 和 Windows 上，规则都由 Go 工具链处理。

假设包目录下有下面的文件：

assets/
  app.js
  .env.example
  _draft.json
  nested/
    .local.yaml

使用 //go:embed assets 时，app.js 会进入 embed.FS，三个隐藏文件不会进入。这个结论也适用于嵌套目录，所以只在外层搜不到文件时改通配符，往往仍会漏掉 nested/.local.yaml。

先区分 assets、assets/* 与 all:assets

这里最容易误判的是 assets/*：它可能让外层的 assets/.env.example 被直接匹配，却不会自动让普通子目录里的隐藏文件也递归出现。因此，需求是“完整保留目录树”时不要靠增加几个通配符碰运气，直接使用 all: 更清晰。

需要保留隐藏文件时改用 all:

把前缀放在模式最前面，并让变量使用 embed.FS。下面的读取路径仍然相对于嵌入文件系统根目录，不能写成本机绝对路径：

package main

import (
    "embed"
    "fmt"
)

// all: 让目录递归包含点号和下划线开头的文件。
//go:embed all:assets
var assets embed.FS

func main() {
    // 路径使用正斜杠，并且包含 embed 目录名。
    data, err := assets.ReadFile("assets/.env.example")
    if err != nil {
        // 读取失败时保留原始错误，便于区分路径错误和构建遗漏。
        panic(err)
    }
    fmt.Print(string(data))
}

如果只需要一个隐藏文件，也可以把它作为明确的单文件模式，例如 //go:embed assets/.env.example。需要注意，string 或 []byte 变量只能接收一个模式且该模式只能匹配一个文件；要浏览多文件目录，使用 embed.FS。

构建失败或运行时找不到文件怎么排查

先看模式，再看路径，最后看构建上下文。可以按下面的顺序处理：

1. 确认指令位置。//go:embed 必须紧挨着包级变量声明，模式相对声明所在 Go 文件的包目录解析。
2. 确认是否真的需要隐藏文件。如果它是本地密钥、开发机配置或临时文件，不要为了“读得到”就使用 all:；改用明确的非敏感模板或构建时注入。
3. 确认目录模式。完整递归用 all:assets，单文件用明确路径；不要把 assets/* 当成递归包含所有层级。
4. 用遍历观察嵌入结果。调试阶段可以临时加入下面的代码，生产代码不必打印敏感文件内容：

import (
    "embed"
    "fmt"
    "io/fs"
)

//go:embed all:assets
var files embed.FS

func listEmbedded() error {
    // 只打印路径，不输出配置内容，避免调试日志泄露数据。
    return fs.WalkDir(files, ".", func(path string, entry fs.DirEntry, err error) error {
        if err != nil {
            return err
        }
        fmt.Println(path)
        return nil
    })
}

若编译阶段提示模式没有匹配到文件，还要检查文件是否位于当前模块内、名称是否包含不允许的特殊字符，以及目录是否为空。all: 只改变隐藏文件的目录遍历规则，不会突破模块边界，也不会把非法路径变成合法路径。

常见问题

all:assets 能嵌入 .git 目录吗？

不能把它理解为“无条件打包一切”。Go 的嵌入规则仍会排除不应打包的模块外路径、符号链接和非法名称；更重要的是，版本库元数据本身也不适合作为应用资源。

为什么 ReadFile(".env.example") 还是报错？

如果模式是 all:assets，完整路径应为 assets/.env.example；如果变量声明的是 //go:embed all:assets/*，也要根据最终 FS 根路径确认目录前缀。先用 WalkDir 打印路径，不要猜。

发布包里需要隐藏模板，应该怎么做？

优先把需要发布的模板移动到明确的资源目录，或显式嵌入单个文件；只有目录树本身有稳定需求时才使用 all:，并在代码审查中确认没有把密钥和本地配置一起编译进去。