Go embed 怎样把子目录暴露为 fs.FS

如果你用 //go:embed assets 嵌入整棵资源树，读取 assets/static/index.html 没有问题，但把这棵树交给静态文件服务时，调用方往往不想一直携带 assets/static 前缀。做法是先得到一个 embed.FS，再用 fs.Sub(allAssets, "assets/static") 切出目标子目录；返回值仍然是标准的 fs.FS，之后读取时直接从 index.html 开始。

官方地址：https://pkg.go.dev/embed

先确认嵌入根里实际存在的路径，再用 fs.Sub 改变消费者看到的根目录。切出后不要继续把原来的 assets/static 前缀传给 ReadFile 或 http.FS，否则排查方向会被路径重复带偏。

先确认 embed.FS 的根目录

//go:embed 的目录模式会把目录下的文件树嵌入包级的 embed.FS。它保存的是只读资源，路径仍以嵌入声明所在包为参照，并使用斜杠分隔。假设项目的资源布局是：

assets/
├── static/
│   ├── index.html
│   └── css/app.css
└── templates/
    └── home.html

对应的声明可以写成：

package web

import "embed"

// allAssets 保留 assets 这一层，便于同一包同时管理静态文件和模板。
//go:embed assets
var allAssets embed.FS

此时，allAssets 看到的是带 assets 前缀的文件树。读取静态首页时，完整路径是 assets/static/index.html；读取模板时，完整路径是 assets/templates/home.html。如果这里的路径判断不清楚，后面的 fs.Sub 就很容易切错层级。

用 fs.Sub 切出目标目录

fs.Sub 接收一个 fs.FS 和目录名，返回以该目录为根的新的 fs.FS。对于 embed.FS，最常见的写法如下：

package web

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

// allAssets 的根仍然是 assets，staticFS 只暴露 assets/static 子树。
//go:embed assets
var allAssets embed.FS

func staticFileSystem() (fs.FS, error) {
    // 切根后，消费者读取 index.html 时不再重复写 assets/static。
    staticFS, err := fs.Sub(allAssets, "assets/static")
    if err != nil {
        // 保留原始错误，调用方可以决定启动失败还是降级。
        return nil, fmt.Errorf("切出静态资源目录: %w", err)
    }
    return staticFS, nil
}

这里的关键不是复制文件，而是包装同一个文件系统视图。原始的 allAssets 仍然可以访问模板；返回的 staticFS 只把 assets/static 当成根。由于函数返回的是 fs.FS，它可以继续传给理解该接口的标准库组件。

把子文件系统交给消费者

以 HTTP 静态文件服务为例，http.FileServer 需要 http.FileSystem，可以通过 http.FS 做适配。挂载路径和文件系统内部路径是两件事：前者属于 URL，后者属于 fs.FS 的文件名。

package main

import (
    "embed"
    "log"
    "net/http"
    "io/fs"
)

//go:embed assets
var allAssets embed.FS

func main() {
    // 先把静态目录切为独立的 fs.FS，屏蔽上层资源前缀。
    staticFS, err := fs.Sub(allAssets, "assets/static")
    if err != nil {
        // 子目录边界不正确时，启动阶段就返回明确错误。
        log.Fatalf("准备静态资源: %v", err)
    }

    // URL 仍以 /static/ 暴露，文件系统内部从 index.html 等相对路径开始。
    handler := http.StripPrefix("/static/", http.FileServer(http.FS(staticFS)))
    http.Handle("/static/", handler)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

访问 /static/index.html 时，HTTP 层去掉的是 URL 前缀；随后文件服务在 staticFS 中查找的相对名字是 index.html。不要把 assets/static/index.html 再拼给这个已经收窄的文件系统。

按证据排查读取失败

遇到 file does not exist 时，先不要改动嵌入声明。沿着“原始根、切出根、消费者路径”三层检查，通常很快能判断是哪一层重复了前缀。

特别要注意，fs.Sub 不会把目录内容复制到新位置；它返回的是一个以子目录为根的文件系统视图。这样做的好处是调用方只关心自己的资源边界，但也意味着路径前缀的变化必须在接口交接处写清楚。

用清单反向确认边界

正式接入前，可以逐项回答下面的问题：

• //go:embed 声明紧挨着包级变量，并且变量类型是 embed.FS 或兼容的 FS 类型吗？
• 原始 embed.FS 中，目标目录的完整路径是否确实是 assets/static？
• fs.Sub 的错误是否被返回或记录，而不是直接丢弃？
• 切出后的消费者是否从 index.html 这样的相对路径开始，而不是重复原始前缀？
• URL 前缀与文件系统内部前缀是否分别处理，没有把两者混成一个路径？

如果只需要访问一个文件，也可以直接使用原始 embed.FS 的完整路径；只有当多个消费者应共享某个子目录、或希望隐藏资源树的上层组织时，才值得用 fs.Sub 把根边界表达出来。

相关问题

• fs.Sub 会复制嵌入文件吗？不会，它返回一个以指定目录为根的 fs.FS 视图。
• 切出后还能读取模板目录吗？不能从这个子 FS 读取不在目标子树中的模板；需要继续使用原始 embed.FS 或为模板切出另一棵子树。
• 为什么 http.StripPrefix 还要配合 fs.Sub？前者处理 URL，后者处理文件系统内部根目录，两者解决的是不同层面的前缀。