Go embed.FS 读取子目录文件时怎么处理相对路径

把模板打进 Go 二进制后，最容易踩的坑不是 embed.FS 不能读子目录，而是把三种路径混在了一起：//go:embed 模式相对源文件所在包目录；FS 方法接收的是相对文件系统根、用斜杠分隔的名字；对外 URL 又是另一套路径。稳定做法是先固定嵌入树，再用 fs.ValidPath 检查输入，必要时用 fs.Sub 把子目录变成新的入口。

例如变量通过 //go:embed assets/web 初始化后，读取入口应写成 web/index.html；如果先得到 webFS，则可以只读取 index.html。不要把磁盘绝对路径或以斜杠开头的 URL 直接传给 ReadFile。

先分清编译期目录和 FS 运行时路径

假设项目结构是 server/assets/web/index.html，声明变量的文件在 server 包内。下面的模式把 assets/web 下的资源嵌入变量，但变量中的路径树仍保留 web 这一层：

package server

import (
    "embed"
    "fmt"
)

// assets 保存编译期打包进二进制的资源树。
//go:embed assets/web
var assets embed.FS

func loadIndex() ([]byte, error) {
    // 路径相对 assets 的 FS 根，而不是相对当前工作目录。
    data, err := assets.ReadFile("web/index.html")
    if err != nil {
        return nil, fmt.Errorf("读取嵌入首页: %w", err)
    }
    return data, nil
}

embed 文档说明，目录模式会递归嵌入目录树；embed.FS 实现了 io/fs.FS，所以它遵守通用文件系统接口的路径约定。这里的关键不是当前进程从哪个目录启动，而是声明与资源的包边界。

用 fs.ValidPath 约束用户传入的相对路径

如果文件名来自请求参数、配置或模板名称，不要先用 filepath.Clean 再塞进 FS。io/fs 的路径统一使用正斜杠；ValidPath 接受 . 和普通的 a/b，拒绝空串、/index.html、web/../secret、末尾斜杠和重复斜杠。

package server

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

func readAsset(root fs.FS, name string) ([]byte, error) {
    // FS 路径不能是磁盘路径，也不能带 ..；先拒绝，再组合。
    if !fs.ValidPath(name) || name == "." {
        return nil, fmt.Errorf("资源路径无效: %q", name)
    }
    // path.Join 使用 /，适合 io/fs；不要换成 filepath.Join。
    fullName := path.Join("web", name)
    return fs.ReadFile(root, fullName)
}

这段检查解决的是“路径格式”问题，不等于授权检查。若业务只允许读取 web 子树，更清晰的方案是先建立 webFS，再对调用方的文件名做 ValidPath；不要让每个调用点都自行拼接前缀。

用 fs.Sub 固定子目录入口

fs.Sub(assets, "web") 返回以 web 为根的子文件系统。这样既保留 fs.FS 接口，又把“允许访问哪棵资源树”变成初始化阶段的明确选择：

func webFileSystem() (fs.FS, error) {
    // 子树根只配置一次，后续调用不再重复拼 web/ 前缀。
    webFS, err := fs.Sub(assets, "web")
    if err != nil {
        return nil, fmt.Errorf("建立 web 资源子树: %w", err)
    }
    return webFS, nil
}

func loadTemplate(webFS fs.FS, name string) ([]byte, error) {
    // 调用方只提供子树内的相对文件名。
    if !fs.ValidPath(name) || name == "." {
        return nil, fmt.Errorf("模板名无效: %q", name)
    }
    return fs.ReadFile(webFS, name)
}

同一个 webFS 还能传给 template.ParseFS 或 http.FileServer(http.FS(webFS))。这是一种“边界前移”的小模式：资源根在初始化时确定，业务函数只处理合法的相对名字，发布到不同工作目录时也不会改变含义。

按发布包边界做验收清单

如果发布后出现“文件不存在”，先打印或记录最终的 FS 名字，检查是否多了一层目录；再确认 //go:embed 模式确实匹配了非空文件。不要通过给路径加 ../ 或改当前工作目录来绕过问题，那只会把目录边界变得不可解释。

相关问题

embed.FS 能不能读取磁盘上的新文件？

不能。它是编译期嵌入的只读资源树；运行时新文件应使用 os.DirFS 等磁盘文件系统。

为什么 filepath.Join 不适合拼 FS 路径？

io/fs 规定路径使用斜杠，path.Join 的语义与它一致；filepath.Join 受操作系统路径分隔符影响，容易把抽象 FS 路径和磁盘路径混为一谈。

fs.Sub 会复制嵌入文件吗？

不会。它返回一个视图，把指定目录映射成新的 FS 根；资源仍来自原来的只读文件系统。

记住这条分界即可：编译期模式决定哪些文件进入发布包，FS 相对路径决定如何找到它们，fs.Sub 决定业务代码看到哪棵子树，fs.ValidPath 则负责把不合规的名字挡在入口外。