Go embed.FS 如何读取嵌入文件的相对路径

用 embed.FS 读取文件时，最容易写错的不是 API，而是文件名。//go:embed 的模式以当前 Go 源文件所在的包目录为基准；嵌入后的文件系统名称使用正斜杠，并且保留匹配到的目录层级。比如嵌入 web/templates/index.html，读取时就写 "web/templates/index.html"。如果希望从 web 下面开始读，再用 fs.Sub 把这个公共前缀变成新的根。

我们在Go开发里经常用到embed把静态文件打包进二进制，部署的时候不用额外带一堆资源文件，非常方便。很多新手刚接触`embed.FS`的时候，都会碰到路径写法不对、找不到嵌入文件的问题，其实只要遵循几个简单的规则，就能很顺利的用相对路径读取到所有嵌入的资源。

使用`embed`嵌入目录资源时，绑定的`embed.FS`对象根目录就是你写`//go:embed`指令时指定的文件夹路径，后续所有调用`fs.ReadFile`、`http.FileServer`这类API的地方，直接传入相对于这个根目录的相对路径字符串就可以正常读取，不需要额外拼接项目根路径或者操作系统绝对路径。

先把 embed.FS 里的名字算对

假设目录如下，Go 文件与 web 同属一个包目录：

assets.go
web/
  templates/index.html
  static/app.css

下面的模式会把匹配到的文件放进一个只读文件系统。读取名仍然从 web 开始，而不是从磁盘根目录开始：

package main

import (
    "embed"
    "fmt"
)

// 该模式相对当前包目录匹配，FS 中会保留 web/templates 前缀。
//go:embed web/templates/index.html web/static/app.css
var content embed.FS

func readTemplate() ([]byte, error) {
    // 读取名使用正斜杠，并完整写出嵌入后的相对路径。
    data, err := content.ReadFile("web/templates/index.html")
    if err != nil {
        return nil, fmt.Errorf("读取嵌入模板失败: %w", err)
    }
    return data, nil
}

这里的关键是“模式”和“读取名”属于同一套相对命名空间。ReadFile("index.html") 不会自动搜索子目录；即使目录里只有一个同名文件，也不能省略 web/templates。

需要短路径时用 fs.Sub 重设根

服务只负责提供 web 目录时，可以先构造子文件系统。这样做不是复制文件，也不是修改原始 FS，而是返回一个以指定目录为根的视图：

package main

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

// 资源仍按包目录相对路径嵌入，原始 FS 的根保持不变。
//go:embed web/templates/* web/static/*
var content embed.FS

func readFromWeb() ([]byte, error) {
    // 把 web 设为子 FS 的根，后续名称从 web 下面计算。
    webFS, err := fs.Sub(content, "web")
    if err != nil {
        return nil, fmt.Errorf("创建 web 子文件系统失败: %w", err)
    }

    // 子 FS 中的相对路径不再重复 web 前缀。
    data, err := fs.ReadFile(webFS, "templates/index.html")
    if err != nil {
        return nil, fmt.Errorf("读取子 FS 文件失败: %w", err)
    }
    return data, nil
}

可把两种写法放在一张速查表里：直接读原始 FS 就写完整名字；先 fs.Sub(content, "web") 后，所有名称都相对新的根。fs.Sub 的第二个参数自身也必须是规范的相对 FS 路径。

场景	文件实际位置	读取参数
直接读取原始 FS	web/templates/index.html	web/templates/index.html
创建 web 子 FS 后	原始 FS 仍在同处	templates/index.html
读取目录	web/templates/	web/templates 或子 FS 中的 templates

路径为什么在 Windows 上也要写斜杠

io/fs 使用的是文件系统接口定义的路径名，不等同于本机磁盘路径。官方 embed 文档明确要求 //go:embed 模式使用正斜杠；路径不能以斜杠开头或结尾，也不能包含 .、.. 或空路径元素。因此下面几类写法都应排除：

• web\\templates\\index.html：把 Windows 分隔符带进 FS 名称，跨平台代码会出现不一致。
• /web/templates/index.html：这是绝对路径形式，不是嵌入树里的相对名字。
• web/../templates/index.html：不能依靠路径清理越过 FS 根目录。

如果业务输入来自 URL 或配置，建议先在业务层定义允许的资源名，再交给 fs.ReadFile；不要为了“修正”输入而直接套 filepath.Clean。需要处理用户提供的文件名时，还要明确拒绝空字符串、绝对路径和含 .. 的片段。

常见问题

为什么 ReadFile("index.html") 会报不存在？

因为文件在 FS 中的完整名字是 web/templates/index.html。只有创建了以 web/templates 为根的子 FS，才可以使用更短的相对名称。

embed.FS.ReadFile 和 fs.ReadFile 选哪个？

只有明确持有 embed.FS 时，直接调用方法最直观；如果函数参数是通用的 fs.FS，使用 fs.ReadFile 更容易替换为本地目录或测试用的文件系统。

可以用 filepath.Join 拼接嵌入路径吗？

不建议。它面向操作系统路径，可能生成反斜杠；嵌入文件和 io/fs 名称应使用正斜杠。固定资源名可直接写字符串，动态片段则应在业务层做严格约束。

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

不会。它提供的是以子目录为根的 FS 视图，读取的数据仍来自原始只读文件系统。

参考：https://pkg.go.dev/embed、https://go.dev/src/embed/embed.go