当前位置：首页 > 文章列表 > Golang > Go教程 > Go embed.FS 如何读取嵌入文件的相对路径

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

来源：17golang原创 2026-09-12 10:23:10 0浏览收藏

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

要点速览

embed.FS 的路径是相对包目录的 slash-separated 名字，不是操作系统绝对路径。
ReadFile 直接读取完整嵌入名；fs.Sub 成功后，子 FS 内部不再重复公共目录。
Windows 也使用 /，不要用 filepath.Join 生成传给 fs.FS 的名字。

我们在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。

Go embed.FS 嵌入模式、包目录和完整读取路径之间的静态关系框图 — 图1：嵌入模式以包目录为边界，完整 FS 名称保留 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`