Go io/fs.Sub 怎样挂载子目录并保持相对路径

当一组模板、静态资源或内置配置都放在同一个目录下时，调用方经常要反复写 templates/ 前缀。Go 的 io/fs 提供了 fs.Sub，可以把原始 fs.FS 的某个子目录挂载成一个新的文件系统，让后续读取从子目录根开始。

官方地址：https://pkg.go.dev/io/fs#Sub

核心做法：先对原始 FS 调用 fs.Sub(rawFS, "templates")，得到子 FS；之后读取 "home.html"，而不是再次读取 "templates/home.html"。fs.Sub 只改变文件名视角，不改变底层资源本身。

先看懂 fs.Sub 改变了哪一层路径

fs.FS 使用的是未带盘符的斜线路径：根目录写成 .，普通路径不能以斜杠开头，也不能包含 ..、空路径段或反斜杠。假设原始 FS 的内容如下：

assets/
└── templates/
    ├── home.html
    └── mail/
        └── reset.html

对原始 FS 调用 fs.ReadFile(rawFS, "templates/home.html") 时，路径包含完整前缀；对 fs.Sub(rawFS, "templates") 的结果调用 fs.ReadFile(subFS, "home.html") 时，templates 已经成为子 FS 的根。

用 embed.FS 挂载 templates 子目录

下面的例子把项目中的模板编译进程序，再把 templates 挂载成独立的 fs.FS。挂载成功后，读取函数只需要关心模板文件名：

package main

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

//go:embed assets/*
var embedded embed.FS

func templateFS() (fs.FS, error) {
	// dir 相对于 embedded 的根；返回值的根会变成 assets/templates。
	return fs.Sub(embedded, "assets/templates")
}

func readTemplate(name string) ([]byte, error) {
	sub, err := templateFS()
	if err != nil {
		return nil, fmt.Errorf("挂载模板目录: %w", err)
	}
	// 子 FS 已经把 templates 作为根，这里不要再拼接 templates/。
	data, err := fs.ReadFile(sub, name)
	if err != nil {
		return nil, fmt.Errorf("读取模板 %q: %w", name, err)
	}
	return data, nil
}

这段代码的关键是两个路径处在不同视角：fs.Sub 的第二个参数是原始 FS 中的路径，fs.ReadFile 的第二个参数是子 FS 中的路径。把两者混用，最常见的结果就是重复前缀后得到“文件不存在”。

把路径和错误边界处理清楚

fs.Sub 返回 (fs.FS, error)，目录不存在、目录名不符合 FS 路径规则，或者目标不是目录时，都应该把错误交给调用方。不要在失败后把它静默替换成原始 FS，否则调用方会突然获得更大的资源范围：

func newAssetFS(raw fs.FS, dir string) (fs.FS, error) {
	// 先检查空字符串、绝对路径和 ..；fs.ValidPath 接受的根目录写法是 "."。
	if dir == "" || !fs.ValidPath(dir) {
		return nil, fmt.Errorf("无效的子目录路径 %q", dir)
	}

	sub, err := fs.Sub(raw, dir)
	if err != nil {
		// 保留底层错误，便于区分目录不存在和权限/实现错误。
		return nil, fmt.Errorf("创建子文件系统 %q: %w", dir, err)
	}
	return sub, nil
}

传入 "." 表示原始 FS 的根；传入 "assets/templates" 表示从该目录建立新的视角。返回的子 FS 仍遵守 fs.FS 的相对路径规则，不能用 ../other.txt 回到父目录，也不能用 /tmp/a 访问宿主机绝对路径。

让模板加载器只接收子 FS

子 FS 的价值不只是少写一个字符串前缀，还能把资源边界放到函数参数上。下面的加载器不需要知道上层目录叫什么，换成磁盘 FS、测试 FS 或 embed.FS 都可以：

package main

import (
	"html/template"
	"io/fs"
)

func loadPage(fsys fs.FS, name string) (*template.Template, error) {
	// ParseFS 接收的是子 FS，模板名始终相对于该 FS 的根目录。
	return template.ParseFS(fsys, name)
}

func loadHome(fsys fs.FS) (*template.Template, error) {
	// 调用方只提供子目录内的文件名，避免重复拼接目录前缀。
	return loadPage(fsys, "home.html")
}

生产代码可以在启动阶段创建一次子 FS，并把它注入需要资源的组件；测试时则可以用 testing/fstest.MapFS 构造同样的目录结构。这样测试重点落在“子目录内的相对路径是否正确”，而不是依赖某个机器上的绝对路径。

常见问题

为什么 fs.Sub 后还要写 templates/？

通常不需要。子 FS 已经把传入的目录当成根，再写一次前缀会查找子目录下的 templates/templates/...。只有没有调用 fs.Sub、仍直接使用原始 FS 时，才应写完整前缀。

fs.Sub 会复制文件或创建新的磁盘目录吗？

不会。它返回一个遵守 fs.FS 接口的子视角，底层数据仍由原始 FS 提供；它适合做路径隔离和组件边界，不是复制操作。

目录不存在时可以退回原始 FS 吗？

除非业务明确允许扩大读取范围，否则不要自动退回。更安全的做法是返回错误，让启动阶段或调用方明确处理配置问题。

总结

fs.Sub 的用法可以记成一句话：原始 FS 用完整路径定位子目录，返回的子 FS 用从该目录根开始的相对路径读取内容。把挂载动作放在初始化阶段，把子 FS 注入模板、资源或配置组件，并保留错误和 fs.ValidPath 边界，就能减少路径前缀重复和目录范围误用。