Go embed.FS 与 os.DirFS 怎么统一资源读取接口

如果一段 Go 代码既要读取二进制里的内置资源，又要在开发阶段读取磁盘目录，最稳妥的做法不是写两个版本的读取函数，而是让调用方只依赖 io/fs.FS。embed.FS 和 os.DirFS 都实现这个接口，差别留在组装阶段处理；文件名则统一使用相对、斜杠分隔的 fs.ValidPath 规则。

先把调用方收敛到 fs.FS

Go 1.16 引入的 io/fs 把“只读文件树”抽象成了统一接口。embed.FS 适合编译时把资源放进程序，os.DirFS 适合把某个磁盘目录作为文件系统根。业务函数只需要知道如何打开一个合法的文件名：

package assets

import (
    "fmt"
    "io/fs"
)

// ReadText 只依赖文件系统接口，调用方无需知道资源来自哪里。
func ReadText(fsys fs.FS, name string) ([]byte, error) {
    // FS 名称必须是相对路径，避免把主机绝对路径带进读取层。
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("invalid asset path %q", name)
    }
    data, err := fs.ReadFile(fsys, name)
    if err != nil {
        return nil, fmt.Errorf("read asset %q: %w", name, err)
    }
    return data, nil
}

这里的关键不是把错误包装得多复杂，而是把边界固定在一个地方。模板、静态文件处理器或配置加载器都可以复用 ReadText，测试时再传入 fstest.MapFS，不必为每种资源来源复制业务逻辑。

embed.FS 与 os.DirFS 的路径差异

两者都实现 fs.FS，但“根”并不相同。//go:embed 的匹配模式相对于声明变量所在的 Go 包目录，读取时通常写 static/index.html；os.DirFS("./public") 则把 ./public 视为根，读取同名文件时只写 static/index.html，不能再把 ./public 拼回去。

fs.ValidPath(".") 表示根目录是合法的；空字符串、以斜杠开头、包含空路径段、./ 或 ../ 组合则不属于合法文件名。这个规则是接口层约束，不等于已经确认文件存在，所以后面仍要处理 fs.ErrNotExist。

用构造函数切换嵌入资源和发布目录

可以把资源来源的选择放到应用启动处。下面的示例展示同一套读取方法如何接收两种实现：

package assets

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

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

type Store struct {
    FS fs.FS
}

// NewEmbedded 用于最终二进制，资源随程序一起发布。
func NewEmbedded() Store {
    return Store{FS: embedded}
}

// NewDirectory 用于本地开发或需要热更新资源的部署。
func NewDirectory(root string) Store {
    return Store{FS: os.DirFS(root)}
}

// Read 复用同一个入口，name 不带磁盘根目录前缀。
func (s Store) Read(name string) ([]byte, error) {
    if !fs.ValidPath(name) {
        return nil, fs.ErrInvalid
    }
    return fs.ReadFile(s.FS, name)
}

正式发布时选择 NewEmbedded()，就要确认 static/* 被构建上下文匹配；选择 NewDirectory("./public")，则要把 public 目录作为发布包的一部分交付。业务层永远只传 static/app.css 这样的逻辑名称。

发布包、相对路径和安全边界

这套抽象解决的是资源接口统一，不会自动替你解决所有部署安全问题。首先，os.DirFS 的根依赖传入目录；如果进程工作目录变化，传入相对目录的含义也可能变化，生产环境更适合在启动配置中明确根目录。其次，DirFS 不等同于 chroot：如果根目录内存在指向外部位置的符号链接，访问仍可能跟随链接，是否允许这类文件要由发布包和运维策略决定。

最后，把“名称合法”和“资源存在”分开记录：fs.ValidPath 失败是调用参数错误，fs.ErrNotExist 则可能是发布包漏文件或嵌入模式没有匹配到目标。这样日志里才能快速判断是代码传错了路径，还是构建产物不完整。

常见问题

为什么 os.DirFS(root).Open("/a.txt") 会失败？

因为 fs.FS 接收的是相对于根的合法名称，开头的斜杠把它变成了绝对路径形式。应传入 a.txt；如果文件位于子目录，就传 static/a.txt。

embed.FS 能不能读取源码目录之外的文件？

不能把任意磁盘路径直接交给 //go:embed。嵌入模式受声明所在包和构建规则约束，需要先把资源放进可匹配的包目录，再用相对 FS 名称读取。

统一成 fs.FS 后还需要保留 os.DirFS 类型判断吗？

通常不需要。只有当程序确实要依赖磁盘特有能力，例如符号链接或文件权限信息时，才在组装层单独处理；纯读取逻辑应继续依赖 fs.FS。