fs.FS & go:embed — 文件系统抽象与静态嵌入

io/fs 把"文件系统"抽象成一个只有 Open(name string) (File, error) 一个方法的接口；go:embed（编译器指令）则把真实目录在编译期冻结成一个 fs.FS 塞进二进制。两者合起来解决的是同一类问题：让"读一组文件"的代码与"文件到底在哪"解耦——生产环境读磁盘，测试用内存 MapFS，发布产物里带默认模板，函数签名一个字都不用改。

这一篇按实测说话（go1.27.0 / Windows），重点纠偏三件事：fs.FS 对路径合法性的硬约束（它不是可选的美化）、go:embed 对 ./_ 开头文件的排除规则（比大多数人的直觉更微妙）、以及空目录/未使用变量这类编译器真实行为（旧手册里有想当然的条目）。

1. fs.FS 的接口与契约

type FS interface {
    Open(name string) (File, error) // 唯一的必选方法
}
type File interface {
    Stat() (FileInfo, error)
    Read([]byte) (int, error)
    Close() error
}
type FileInfo struct-ish { Name/Size/Mode/ModTime/IsDir/Sys } // 元信息
type DirEntry interface {                                     // 比 FileInfo 轻量
    Name() string; IsDir() bool; Type() FileMode; Info() (FileInfo, error)
}

真正的契约在 name 上，由 fs.ValidPath 定义：只能用 / 分隔、不能以 / 开头、不能含 . 或 .. 元素、空串非法、. 表示根。目录用 /，根用 .，所有函数都按这套名字工作——这意味着 fs.FS 里的路径天生免疫目录遍历，也意味着把 OS 路径直接塞进来一定会失败。

实测两种"非法名字"的错误形状并不一致：

_, err := embedFS.Open("assets/../assets/note.txt")
// open assets/../assets/note.txt: file does not exist —— 统一按"不存在"处理

_, err := os.DirFS(dir).ReadFile? // 用 fs.ReadFile(os.DirFS(dir), "../out.bin")
// readfile ../out.bin: invalid argument —— errors.Is(err, fs.ErrInvalid) 为 true

两条都拒绝，但错误类型不同：embed.FS 把所有非法/缺失路径统一成 fs.ErrNotExist，os.DirFS 对非法路径给 fs.ErrInvalid。别用 errors.Is(err, fs.ErrNotExist) 来区分"路径非法"和"文件不存在"——在 fs.FS 抽象下这两者本来就不该被区分（否则探测文件是否存在又依赖实现细节）。

可选接口：能力探测，按需实现

fs 包定义了一组可选接口，fs.ReadFile/fs.ReadDir/fs.Glob/fs.Sub/fs.Stat 等函数会先探测 FS 是否原生实现（有就直达，没有就走 Open 通用路径）：

fs.ReadDirFS   // ReadDir(name) ([]DirEntry, error)
fs.ReadFileFS  // ReadFile(name) ([]byte, error)
fs.GlobFS      // Glob(pattern) ([]string, error)
fs.SubFS       // Sub(dir) (FS, error)
fs.StatFS      // Stat(name) (FileInfo, error)
fs.ReadLinkFS  // ReadLink + Lstat（Go 1.25 起，含符号链接的 FS 才实现）

没有 fs.WalkDirFS——遍历永远由 fs.WalkDir 自己基于 ReadDir 拼出来。实测（go1.27.0 类型断言）各实现的支持矩阵：

• embed.FS：五个全有——Open/ReadDir/ReadFile/Glob/Sub 都是它的方法（go doc embed.FS），http.FileServer、模板解析都走快路径。
• os.DirFS：只有 ReadDirFS/ReadFileFS/StatFS/ReadLinkFS，没有 GlobFS 和 SubFS（fs.Glob/fs.Sub 会落到通用慢路径，功能不受影响，只是多做词法模拟）。官方文档同时警告：DirFS 只保证 Open 拼出的路径以 root 开头，符号链接指向树外照样能访问——它不是 chroot；要硬边界用 Root.FS()。

2. 常用函数速查

data, err := fs.ReadFile(fsys, "config.json")     // 等价 os.ReadFile 的 FS 版
entries, err := fs.ReadDir(fsys, ".")             // 按名字排序（实测含点文件在前）
matches, err := fs.Glob(fsys, "*.go")             // 模式里不能出现 ..（实测报 invalid pattern）
sub, err := fs.Sub(fsys, "templates")             // 子树视图：sub 的 "." 是 fsys 的 "templates"
err = fs.WalkDir(fsys, ".", func(p string, d fs.DirEntry, err error) error { ... })
root := os.DirFS("./data")                        // 真实目录 -> FS
ok := fs.ValidPath("a/b")                         // 合法性判断（不含 ..、绝对路径等）
err = fs.WalkDir(fsys, ".", walkFn)               // fs.SkipDir / fs.SkipAll 同 filepath

两个高频困惑：

• os.DirFS(dir) 返回的是"根视图"：Open("index.html") 映射到 dir/index.html；写成 Open("dir/index.html") 就变成 dir/dir/index.html。按官方文档它实现 StatFS/ReadFileFS/ReadDirFS/ReadLinkFS（实测断言一致），定位是"只读、宽松"——文档明确说它不是 chroot：root 下的符号链接指向树外照样能读，相对路径的根还会受后续 Chdir 影响。需要硬边界用 os.Root（实测对比见 os-file.md §4.1：DirFS 对 .. 报 invalid argument，Root 报 path escapes from parent；要"带安全边界的 fs.FS"用 Root.FS()）。
• fs.Sub vs 手工前缀：Sub 返回的视图会把 Open 的名字透明地加上前缀并校验合法性，别用"字符串拼接再 Open"替代它——拼接就重新引入了遍历风险。

测试替身 testing/fstest.MapFS 是 map[string]*MapFile 字面量（Data/Mode/ModTime/Sys），路径永远用 /，即使在 Windows 上；配合 fstest.TestFS(fsys, expected...) 还能一次性校验 WalkDir/Glob/Sub 的一致性，是给自研 FS 用的合规测试。

3. fs.FS vs os：什么时候用哪个

// 紧耦合：测试需要准备真实文件
func LoadConfig(path string) (*Config, error) {
    data, err := os.ReadFile(path)
    ...
}

// 接受 fs.FS：生产传 os.DirFS(".") 或嵌入资源，测试传 MapFS
func LoadConfig(fsys fs.FS, name string) (*Config, error) {
    data, err := fs.ReadFile(fsys, name)
    ...
}

读走 fs.FS、写走 os 是稳定的架构约定：fs.File 没有 Write，fs.FS 没有 Create/Remove/Chmod，这不是缺失，是刻意的——写操作涉及权限、原子性、并发这些抽象层保证不了的东西。需要"可写的 FS"时看具体库（afero 一类，属第三方），标准库不背这个锅。

4. go:embed 基本规则

//go:embed 是编译器指令（go 工具处理，_ "embed" 导入即可，除非用 embed.FS 类型才正式导入）。三种接收变量：

//go:embed config.json
var configData string          // 文本：原样内容，实测 8 字节文件含尾部换行

//go:embed logo.png
var logoData []byte            // 二进制：文档要求按只读处理

//go:embed static
var staticFS embed.FS          // 目录 -> 实现 fs.FS 的完整树

实测编译器行为（逐条在 go1.27.0 验证）：

• 指令必须紧邻"单变量声明"。官方文档允许两者之间只夹空行或 // 注释——实测 //go:embed note.txt 与 var c string 之间隔空行、隔普通注释都照常生效（“空行导致指令失效"是讹传）。真正的硬错误是：同一行声明两个变量（实测 go:embed cannot apply to multiple vars）、指令挂在函数上（实测 misplaced go:embed directive）。
• 模式相对于源文件所在目录，不能 ..、不能绝对路径、跨平台写法必须用 /。实测 Windows 上 sub\x.txt 也能命中（cmd/go 按 OS 解析），但同一份代码到 Linux 上 \ 只是普通文件名字符，会以"no matching files found"报错——别赌平台宽容。
• 空目录不能嵌入：//go:embed emptydir 实测报 pattern emptydir: cannot embed directory emptydir: contains no embeddable files。旧手册说"Go 1.22 有改善"是想当然——没有任何版本能嵌入空目录，embed.FS 只记录文件。要保住一个"空"配置目录，放占位文件（注意占位文件常叫 .gitkeep，而 . 开头的文件在下一节的规则里会被排除——要么 all:，要么用 README/keep.txt 这种不加点的名字）。
• //go:embed 声明的包级变量就算没被引用也能编译——旧手册"未使用导致编译错误"不成立（实测通过）。真正报错的是指令本身的问题（模式无匹配、变量类型不对、用在非包级变量上）。
• 嵌入的 string/[]byte 指向只读数据段，运行时写它会崩；把它交给会就地修改的库（如 bytes.Title 风格的原地操作）前先 bytes.Clone。
• 变量类型只有 string、[]byte、embed.FS 三种合法；map 之类直接编译错误。

5. 隐藏文件的排除规则（最容易记错的一节）

直觉是”go:embed 不嵌入 ./_ 开头的文件"。不完全对——排除只发生在"模式命中一个目录"的递归展开时。实测三种写法对同一棵树（assets/ 下有 .dotfile、_hidden.txt、note.txt、sub/inner.txt）的结果：

//go:embed all:assets  →  ./ assets/.dotfile assets/_hidden.txt assets/note.txt assets/sub/inner.txt
//go:embed assets      →  ./ assets/note.txt assets/sub/inner.txt          // 目录递归：排除 . 和 _
//go:embed assets/*    →  ./ assets/.dotfile assets/_hidden.txt assets/note.txt assets/sub/inner.txt

规则拆成两条：

1. 模式直接命名目录（static、static/sub）：递归包含子树，但跳过文件名以 . 或 _ 开头的项；all: 前缀取消跳过。
2. 模式含通配符（static/*、static/*.css）：按 path.Match 语义展开，* 可以匹配 .dotfile 和 _hidden.txt；模式命中的目录同样会递归展开子树。实测 assets/* 顶层点文件直接命中、sub/inner.txt 也完整拿到。

所以 static/* 与 all:static 在这棵树里结果相同，但语义来源不同：前者是"* 本来就匹配点文件"，后者是"显式取消排除"。要"全都要"就写 all:，意图明确；做 Web 资源服务器时点文件（.env、.git/）进 FS 是安全事故，这时候故意用裸目录模式让编译器帮你挡掉第一层。

另一个推论：template.ParseFS(plainFS, "assets/_hidden.txt") 实测报 template: pattern matches no files——因为 _hidden.txt 在编译期就不在 FS 里，运行期的模式再怎么精确也找不到。“文件明明存在却嵌入不进来"先查这条。

6. 实战组合：把 embed 和 fs 串起来

package main

import (
    "embed"
    "io/fs"
    "net/http"
    "text/template"
)

//go:embed all:templates all:static
var resources embed.FS

func main() {
    // 1) 模板：fs.Sub 收窄根，ParseFS 直接吃 FS
    tmplFS, _ := fs.Sub(resources, "templates")
    tmpl := template.Must(template.ParseFS(tmplFS, "*.html"))

    // 2) 静态资源：http.FS 包一层就能当文件服务器（embed 的 File 实现了
    //    io.Seeker —— 实测 true，所以 Range 请求可用）
    staticFS, _ := fs.Sub(resources, "static")
    http.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.FS(staticFS))))

    // 3) 默认配置 + 外部覆盖：embed 兜底，磁盘优先
    serve(tmpl, staticFS)
}

func loadConfig(name string) []byte {
    if data, err := os.ReadFile(name); err == nil {
        return data // 外部文件存在就用外部
    }
    data, _ := resources.ReadFile("config/" + name) // 否则用嵌入的默认值
    return data
}

这套组合的每个环节都有实测依据：fs.Sub 对 embed.FS 工作正常（err=nil）；template.ParseFS 渲染嵌入文件输出与源文件逐字节一致（"visible\n" 含换行）；embed.FS 的 Open 目录名成功（配合 fs.ReadDir 可列目录）。

嵌入文件没有"修改时间”：FileInfo.ModTime() 返回零值。这直接影响 http.FileServer 的 Last-Modified/If-Modified-Since 缓存语义（永远过期/行为依实现而定），做静态资源缓存要上 ETag 或内容哈希文件名，别依赖 mtime。

7. 陷阱汇总

8. 实战建议

库函数读资源，参数收 fs.FS；调用方决定来源。 os.DirFS、embed.FS、fstest.MapFS、zip 里的 FS 都满足同一个接口，函数内部只写 fs.ReadFile(fsys, name) 这一种形状。命名参数（如 New(fsys fs.FS)）比"传个 path 字符串"多了一层安全——FS 抽象帮你挡了遍历（§1），而字符串路径挡不住。

发布单二进制程序时按"模板/静态资源/默认配置 → embed，用户数据/日志 → os 路径"划线。 典型组合是本文 §6 的"嵌入兜底 + 外部覆盖"；Go 生态工具（golang-migrate、swagger、前端资源）普遍吃 fs.FS，接口现成。资源目录别叫 . 开头名字，否则要处理 §5 的排除规则。

给自定义 FS 上线前跑一遍 fstest.TestFS。 它把 Open/ReadDir/Glob/Sub/WalkDir 的一致性全查一遍——手写 FS 实现十有八九栽在 ReadDir 忘了排序或 Open(".") 没处理目录这三种细节上。

需要写操作就回到 os，需要安全边界就回到 os.Root。 fs.FS 是只读抽象，别为它设计"半可写"的怪接口（WriteFile 塞进自定义 FS 是常见的架构异味）；os.Root 的受限可写视图（Create/OpenFile/RemoveAll 全在 root 内）已经有完整方法集，够用。

相关阅读：os-file.md（os.Root 与 os.CopyFS(dir, fsys) ——后者的源参数正是 fs.FS，embed 目录可以直接复制落地）、path-filepath.md（两套路径规则的边界与转换）、text-template 篇（../04-编码与数据处理/text-template.md，ParseFS 与 Clone）、compress-archive.md（zip.Reader 同样实现 fs.FS，一个接口四种来源）、../07-附录/最佳实践清单.md。