Go embed 怎样按子目录读取静态资源

Go embed 按子目录读取资源有两种写法：在原始 embed.FS 上使用包含前缀的完整相对路径，或者先用 fs.Sub 建立子目录视图，再从新根读取。比如同一份样式文件，原始视图使用 static/css/site.css，子视图使用 css/site.css。不要把操作系统的工作目录带入这两种路径。

我更倾向于给调用方一个固定根的资源接口。以随程序交付一个静态站点为例，业务函数只需认识 css 和 js，不必到处重复 static 前缀。这里的目录和函数是原创示例，不是一次线上故障复盘，也不代表代码已经在本机运行。

文件存在却读不到时先看根目录

假设包目录里有 resources.go、static/css/site.css 和 static/js/site.js。资源磁盘位置、编译指令的匹配位置、运行时文件系统根，是三个不同的概念。用 //go:embed static 声明 assets 后，static 不会自动从文件名中消失。

因此，assets.ReadFile("static/css/site.css") 才对应上述文件。若改成 assets.ReadFile("css/site.css")，寻找的是原始根下另一条路径。看到“文件不存在”时，我会先核对完整名称与大小写，而不是修改启动脚本中的工作目录。文件是在编译时嵌入程序的，启动后到磁盘上寻找同名文件是另一套机制。

检查资源是否进入编译包

embed 指令的匹配以声明它的 Go 源文件所在包目录为基准，并采用斜杠。它不能借助 ../ 引用父目录。将资源放在正确包内，比运行时拼接一个绝对磁盘路径更直接。资源生成工具也应该先生成文件，再构建程序；构建完成后补文件不会修改已存在的二进制。

直接指定目录会递归纳入允许的子树文件，但默认遍历会排除以点号或下划线开头的文件、目录。确实需要这些资源时，可以研究 all:static；我不建议为了修复一个丢失文件就无条件扩大嵌入范围，先确认其中没有私有配置。通配符与目录名的匹配细节也不完全相同，不能把 static/* 简单当成目录写法的同义词。

模式没有匹配到文件或非空目录时会导致构建失败，空目录本身不是资源。符号链接、其他模块边界等也受到限制。构建阶段失败，应回到目录和模式；构建成功但读取失败，则继续检查文件系统名称。官方指令说明：https://pkg.go.dev/embed。

用 fs.Sub 固定子目录根

下面的文件可放进名为 resources 的包。预先准备好 static/css/site.css，样式内容可以是自己的任意文本。函数把视图固定在 static，读取时只使用相对这个根的 css/site.css；调用方获得字节和错误，不依赖 HTTP 服务。

package resources

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

// 静态目录应与本文件位于同一个包目录内。
//go:embed static
var assets embed.FS

func ReadStyle() ([]byte, error) {
    // 子文件系统以 static 为根，不复制资源文件。
    site, err := fs.Sub(assets, "static")
    if err != nil {
        return nil, fmt.Errorf("建立资源视图: %w", err)
    }
    data, err := fs.ReadFile(site, "css/site.css")
    if err != nil {
        return nil, fmt.Errorf("读取样式: %w", err)
    }
    return data, nil
}

子视图不是复制文件，也不是把资源解压到磁盘。它改变的是后续名称的解释基准。对本例来说，原始 assets、static 子目录、site 子视图、两种路径名称和 css 文件，共同构成同一个资源访问结构。

我喜欢把 Sub 放在资源包内部，让业务代码不用猜该加几层前缀。代价是包必须清楚地约定暴露哪个根：如果既导出 assets 又导出 site，调用者可能混用名称。对小项目，保留一个统一读取函数往往比同时公开多个视图更容易维护。

按相同根枚举并读取资源

想列出 css 子目录，就继续在 site 上调用 fs.ReadDir(site, "css")。以下函数与上一段放在同一个源文件，共用 imports 和 assets；它返回可直接用于 site 读取的名称，而不是带 static 前缀的原始名称。

func ListCSS() ([]string, error) {
    site, err := fs.Sub(assets, "static")
    if err != nil {
        return nil, err
    }
    entries, err := fs.ReadDir(site, "css")
    if err != nil {
        return nil, err
    }
    names := make([]string, 0, len(entries))
    for _, entry := range entries {
        if entry.IsDir() {
            continue // 本例只列出当前目录的文件。
        }
        names = append(names, "css/"+entry.Name())
    }
    return names, nil
}

ReadDir 列举的是指定目录的直接条目，不是整个子树；需要递归时另用 WalkDir。entry.Name() 是文件基本名，所以本例明确补上 css/。同一列表若交给 assets 直接读取，就需要恢复 static/，否则读取者和列表生产者使用了不同坐标系。根目录枚举使用 "."，不是空字符串。

名称使用斜杠分隔，不使用 filepath.Join 生成可能含反斜杠的系统路径。标准文件系统名称不接受绝对路径、空路径元素或点点路径元素；不要靠“清洗成合法路径”掩盖调用者传错根的问题。官方路径与接口约定：https://pkg.go.dev/io/fs。

把缺失与路径错误分开处理

一个容易忽略的细节是：fs.Sub(assets, "static") 返回成功，不能单独证明 static 已存在。标准实现可以先返回一个子视图，将实际文件访问留到后续调用。因此初始化时若必须保证资源可用，应读取必需文件或枚举目标目录，而不是只检查 Sub 的 err。

我会在错误中保留操作和目标名称，并通过 %w 保留错误链。需要区分缺失资源时，调用者可用 errors.Is(err, fs.ErrNotExist)，同时记录原始错误；不要把所有错误都改写为“请修改工作目录”。错误可能是名称不合法，也可能是该文件根本未进入当前二进制。

反向排查时，把子视图的 css/site.css 换算回原始视图的 static/css/site.css：两边都缺失，重点检查资源内容与构建输入；原始视图能读取而子视图读不到，重点检查 Sub 根与子路径；旧二进制缺失而重新构建后具备文件，说明更新没有进入此前的构建产物。这些是读者可执行的判断方法，不是本文已得到的实验结论。Sub 的官方实现：https://go.dev/src/io/fs/sub.go。

交付前的检查项与常见问答

• 声明文件与 static 的相对位置是否正确，必需文件是否在构建前生成。
• 调用者是否统一使用原始根或子根，是否多写或漏写 static 前缀。
• 目录枚举返回的名称是否与读取接口使用同一根。
• 关键资源缺失时是否返回错误，而不是静默交付空内容。
• 资源变更后是否重新构建并部署了对应二进制。

改变启动目录能修复 embed 读取吗？

通常不能。这里读取的是编译时写入的资源与逻辑路径；如果修改启动目录后行为改变，应检查是否混用了 os.ReadFile 等磁盘读取方式。

可以直接对 embed.FS 调用 ReadFile 吗？

可以。只读取一两个文件时，完整相对路径更简洁。只有需要把一个子树作为独立资源根提供给多个使用方时，Sub 才更有价值。

修改磁盘上的 CSS 会立即更新程序吗？

不会修改已经嵌入当前二进制的那份内容。开发时若需要热更新，可以明确设计另一种磁盘资源模式，但不要把它与嵌入模式偷偷混在一起。

对需要单文件交付且资源随版本固定的程序，我会选 embed 加明确的子根；对需要频繁在线调整素材的应用，则应重新考虑资源存储方式。子目录读取本身并不复杂，真正值得统一的是“谁定义根、谁提供名称、谁处理缺失”这三个接口约定。