Go embed 同名文件来自多个目录时如何避免构建失败

我遇到过一种很像“同名文件冲突”的 Go embed 问题：assets/a/config.json 和 assets/b/config.json 都叫 config.json，改成多目录匹配后，项目却在构建阶段报错。先给结论：如果变量类型是 embed.FS，Go 会保留目录前缀，这两个文件实际是两条不同路径；真正需要排查的通常是把多个匹配结果塞进了 string/[]byte，或 pattern 越过模块边界、表达式无效。

先判断冲突发生在哪一层

//go:embed 的 pattern 相对声明变量所在的包目录解析。目录匹配会把目录树带进文件系统，所以同名文件只要父目录不同，就不会被压平成同一个 basename。下面这组映射更接近实际结果：

因此，看到“同名”时不要先重命名文件。先确认代码是不是把目录前缀丢掉了，或者用宽泛的目录 pattern 与子文件 pattern 重叠。

把多个文件交给 embed.FS

多目录资源适合声明为 embed.FS。读取时使用嵌入后的完整路径，代码可以这样组织：

package assets

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

// content 保存两个目录的资源；目录前缀会成为 FS 路径的一部分。
//go:embed assets/a/* assets/b/*
var content embed.FS

func ReadConfig(path string) ([]byte, error) {
    // 调用方必须传入 assets/a/config.json 这类完整路径，避免来源混淆。
    data, err := fs.ReadFile(content, path)
    if err != nil {
        // 把路径带回错误，便于区分文件不存在和内容解析失败。
        return nil, fmt.Errorf("读取嵌入资源 %q: %w", path, err)
    }
    return data, nil
}

这里的关键不是变量名，而是路径契约。若业务只接受一个“配置名”，应在自己的映射层把 service-a 转成 assets/a/config.json，不要在 FS 层用 basename 猜来源。

最容易误用的是 string 和 []byte

string 或 []byte 适合嵌入一个确定文件。把多个 pattern 写给它们，构建器无法把多个文件合并成一个值，就会失败。需要多个文件时改成 embed.FS；如果确实只需一个文件，就把 pattern 收窄到单个明确路径：

import _ "embed"

// 单值变量只绑定一个确定文件，适合固定的默认配置。
//go:embed assets/a/config.json
var defaultConfig []byte

另一个常见坑是 pattern 本身无效：匹配到模块外目录、嵌套 go.mod、符号链接，或者某个 pattern 一个文件都匹配不到，都可能让构建失败。资源目录里还有以点号或下划线开头的文件时，也要记住普通目录匹配默认会排除它们；确需包含时再评估 all: 前缀。

把读取路径和构建清单一起回归

文章里的示例不应把插图当成运行截图。实际项目可以先查看 Go 工具收集到的 pattern 和文件，再运行构建：

# 查看包的嵌入 pattern 与最终文件清单；包路径按项目实际值替换。
go list -json ./path/to/assets

# 编译当前包，尽早发现无效 pattern 或模块边界问题。
go build ./path/to/assets

在 JSON 输出中重点关注 EmbedPatterns 和 EmbedFiles。最后分别读取 assets/a/config.json、assets/b/config.json，确认调用方没有把两个路径缩成同一个键。这样既能证明“同名文件可共存”，也能及时发现真正的模式重叠。

常见问题

两个目录都有 index.html，embed.FS 会覆盖吗？

不会，只要目录不同，访问路径仍分别是 dir-a/index.html 和 dir-b/index.html。覆盖风险来自你自己的路径重写或错误的 basename 映射。

能不能把多个目录直接嵌入 string？

不能。string 和 []byte 只适合单个文件；多个文件请使用 embed.FS，或者在构建前明确生成一个合并文件。

为什么改成 embed.FS 后仍然构建失败？

继续检查每个 pattern 是否有效、是否匹配到文件、是否触碰嵌套模块或模块外目录，并确认 //go:embed 紧邻包级变量声明。

处理这类问题时，我通常保留资源目录的语义边界，把完整嵌入路径当作稳定 API，再让 go list 和 go build 负责最后一轮机械检查。这样比为了消除“同名”而批量改文件名更稳。