只实现fs.FS接口无法满足实际需求，因其仅含Open方法；必须按场景组合fs.ReadDirFS、fs.StatFS等接口，否则fs.ReadDir等调用会panic，且http.FileServer等标准组件将不可用。
Go 的 fs.FS 接口本身不支持写入、遍历或元数据操作，仅靠实现 Open 方法无法构成“可用”的自定义文件系统——必须按需组合其他接口（如 fs.ReadDirFS、fs.StatFS、fs.ReadFileFS）才能匹配真实使用场景。
为什么只实现 fs.FS 会卡在 os.DirFS 之外的几乎所有场景
标准库中只有 os.DirFS 和少数测试用 fstest.MapFS 是完整实现（含目录读取、Stat、ReadFile 等），而 fs.FS 接口本身只强制要求 Open(name string) (fs.File, error)。这意味着：
- 如果你只实现
fs.FS，fs.ReadDir会 panic：它内部会尝试类型断言为fs.ReadDirFS，失败后直接报"fs: ReadDir not implemented" -
embed.FS能用，是因为它同时实现了fs.ReadDirFS和fs.ReadFileFS；zipfs（来自 Go-FUSE）也额外实现了fs.ReadDirFS才支持ls类操作 - 任何想被
http.FileServer、embed.FS兼容层、或第三方工具（如go-fsimpl）识别的 FS，都得显式提供所需接口，不是“实现了fs.FS就万事大吉”
如何判断你的自定义 FS 缺少哪个接口
运行时最常暴露缺失接口的地方是错误信息和 panic 位置，比如：
-
fs: ReadDir not implemented→ 缺fs.ReadDirFS（需实现ReadDir(name string) ([]fs.DirEntry, error)） -
fs: Stat not implemented→ 缺fs.StatFS（需实现Stat(name string) (fs.FileInfo, error)） -
fs: ReadFile not implemented→ 缺fs.ReadFileFS（需实现ReadFile(name string) ([]byte, error)） - 用
http.FileServer(http.FS(yourFS))报 404 却没日志 → 很可能Open返回了nilfs.File或未正确实现fs.File.Stat()
常见自定义 FS 实现路径与取舍点
根据目标用途选择最小必要接口集，避免过度实现：
立即学习“go语言免费学习笔记（深入）”；
- 只读资源嵌入（如配置模板）→ 优先实现
fs.ReadFileFS+fs.ReadDirFS，Open可返回一个内存bytes.Reader包装的fs.File，无需真实文件句柄 - 网络后端（HTTP/S3/Git）→ 必须实现
fs.StatFS（否则http.FileServer无法判断是否为目录），ReadDirFS建议缓存一次响应结果，避免每次ls都发请求 - 测试模拟（
fstest.MapFS替代）→ 直接复用fstest.MapFS，它已完整实现全部只读接口；若需写入能力，别自己造轮子，改用hackpadfs或go-fsimpl的可写扩展方案 - FUSE 挂载（如
zipfs）→ 必须实现fs.ReadDirFS和fs.StatFS，且fs.File实例要支持Seek、Readdir（FUSE nodefs 对这些有强依赖）
容易忽略的细节：路径合法性与 fs.ValidPath
fs.ValidPath 不是装饰性函数，而是安全边界守门员：
- 所有传入
Open、ReadDir、Stat的name参数，都应先过fs.ValidPath(name)校验；否则../etc/passwd这类路径可能绕过你的逻辑直接穿透到后端存储 -
embed.FS和fstest.MapFS内部都调用了它；但自定义实现时很多人直接跳过，导致本地调试正常、上线后被路径遍历攻击 - 注意：空字符串
""是合法路径（表示根目录），fs.ValidPath("")返回true；而"."、".."、含"\x00"或控制字符的路径一律为false
真正麻烦的从来不是“怎么实现 Open”，而是“哪些接口会被谁调用、在什么上下文里、没实现时会怎样崩溃”。接口组合不是可选项，是调用链决定的硬约束。
