Go fs.Sub 截取嵌入目录后为什么仍然出现前缀

我第一次把静态资源从 embed.FS 拆成子文件系统时，误以为 fs.Sub(all, "assets") 会改写嵌入文件本身。结果日志里依然出现 assets/css/app.css，一度以为 fs.Sub 没有生效。

实际情况是：fs.Sub 只改变返回的 FS 视图，不改变原始 embed.FS，也不会替你修改 HTTP 路由。如果你确实通过子 FS 调用 ReadFile、ReadDir 或 WalkDir，文件名应从子目录根开始写；仍然看到前缀，通常是读取时还用了原 FS，或者前缀来自 URL 挂载层。

先判断前缀到底来自哪一层

这个问题最容易混淆的是“文件系统路径”和“浏览器 URL”。假设项目中有 assets/index.html，声明为 embed.FS 后，原 FS 里看到的是 assets/index.html。调用 fs.Sub(all, "assets") 后，子 FS 的根已经移动到 assets，所以对它调用 fs.ReadFile(sub, "index.html") 才是对应写法。

如果日志仍是 assets/index.html，先检查日志打印的对象是否还是 all。如果浏览器访问的是 /static/index.html，那只是路由前缀；它可以和文件系统里的 index.html 同时存在，并不说明 fs.Sub 失败。

fs.Sub 建立的是相对根，不是字符串替换

fs.Sub(fsys, "assets") 的含义是返回一个以 assets 为根的 fs.FS。它不会把 all 内部的目录删除，也不会把同一个 embed.FS 变成另一个对象。下面的最小写法把访问入口固定在子 FS 上：

package main

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

// all 保留完整的嵌入目录树，文件实际位于 assets/css/app.css。
//go:embed assets
var all embed.FS

func main() {
	// 把 assets 设为新的相对根，后续名称不再重复写 assets/。
	sub, err := fs.Sub(all, "assets")
	if err != nil {
		panic(err)
	}

	// 对子 FS 读取时使用相对于 assets 的路径。
	data, err := fs.ReadFile(sub, "css/app.css")
	if err != nil {
		panic(err)
	}
	fmt.Println(len(data))
}

这里的关键不是变量名，而是调用链：fs.ReadFile(sub, "css/app.css") 会被映射到原 FS 的 assets/css/app.css。如果改成 fs.ReadFile(all, "css/app.css")，自然会找不到；如果改成 fs.ReadFile(sub, "assets/css/app.css")，则会多拼一层目录。

遍历和读取要统一使用同一个 FS

项目里常见的隐性错误是：读取函数用了 sub，但遍历函数仍然从 all 开始。这样会让前缀看起来“偶尔出现”。统一入口后，WalkDir 的根也应该是子 FS 的 "."，回调拿到的路径就是子目录内的相对路径。

// listAssets 只暴露 assets 子树，避免调用方再次拼接目录前缀。
func listAssets(fsys fs.FS) error {
	return fs.WalkDir(fsys, ".", func(name string, entry fs.DirEntry, walkErr error) error {
		// 先处理回调错误，避免把失败访问误当成目录项。
		if walkErr != nil {
			return walkErr
		}
		if !entry.IsDir() {
			fmt.Println(name) // 这里打印 css/app.css，而不是 assets/css/app.css。
		}
		return nil
	})
}

同理，fs.ReadDir(sub, ".") 列出的是子根下的项目；fs.ReadFile(sub, "index.html") 读取的是子根下的文件。不要把原 FS 的路径表直接复制给子 FS 使用。

HTTP 里的 /static/ 不是嵌入目录前缀

服务静态文件时经常写成 http.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.FS(sub))))。此时浏览器地址仍然带 /static/，因为它属于 URL 路由；StripPrefix 去掉它后，文件服务器才会向 sub 请求 index.html 或其他相对名称。

如果你希望 URL 直接是根路径，可以改变路由挂载方式；如果你希望文件系统代码保持独立，则保留 sub 作为资源边界。调试时分别打印“请求 URL”“StripPrefix 后的名称”和“FS 传入名称”，比只打印一个最终字符串更容易定位。

几个容易误判的边界

另外，dir 和子 FS 接收的文件名都要符合 io/fs 的合法路径规则；不要传入以斜杠开头、包含 .. 的路径。嵌入资源的目录前缀如果需要隐藏，应在创建子 FS 后把它作为唯一入口传递，而不是在每个业务函数里手工裁剪字符串。

相关问题

fs.Sub 会修改原来的 embed.FS 吗？

不会。它返回新的 FS 视图，原来的 embed.FS 仍然可以按完整路径访问。

为什么 fs.Sub 不报错，读取时却提示文件不存在？

目录参数格式合法并不等于目录实际存在；创建视图和访问内容是两个时机，应该在创建后立即读取或统计根目录确认。

fs.Sub 能防止访问子目录之外的真实文件吗？

不能把它当作通用安全沙箱。它解决的是 FS 命名和访问视图；涉及操作系统目录的安全约束时，还需要专门的目录边界机制。

排查这类前缀问题时，我现在会固定记录三列：原 FS 传入名、子 FS 传入名、HTTP 路由名。只要三列分开，fs.Sub 通常并没有失效，真正的问题只是调用入口没有统一。