WalkDir 找到的是逻辑名不是磁盘路径：Go fs.FS 迁移后的安全转换

把 os.File 遍历迁移到 io/fs.FS 后，最容易踩的坑不是遍历本身，而是把回调里的 name 直接当成磁盘绝对路径。结论先说：fs.WalkDir 返回的是相对于 FS 根的逻辑名，统一使用斜杠；只有交给操作系统 API 或外部命令时，才用保存的物理根目录完成转换。

本文要点：一是分清两套路径语义；二是把转换集中在边界；三是用根目录、子目录和跨平台分隔符做回归。

先把 fs.FS 的路径契约说清楚

os.DirFS(root) 把一个目录包装成 FS。对这个 FS 调用 WalkDir 时，回调拿到的路径是 FS 内部名称，例如 assets/css/app.css，不是 /srv/site/assets/css/app.css。它适合继续传给 fs.Open、fs.ReadFile 这类 FS API；它不携带你创建 FS 时的物理根目录。

这也是迁移后“文件明明存在却找不到”的典型原因：程序把相对逻辑名交给只接受操作系统路径的工具，工具便在当前工作目录下寻找它。不要在遍历回调里猜测绝对路径，也不要用字符串前缀判断平台。

迁移时为什么会把逻辑名误当绝对路径

旧代码往往同时持有一个物理目录和 *os.File，目录变量在很多函数里自然变成了“完整路径”的代名词。切到 fs.FS 后，遍历接口刻意隐藏了底层实现，回调参数只表达“这个条目在 FS 中叫什么”。这不是信息丢失，而是接口契约改变。

root, err := filepath.Abs("./site")
if err != nil { return err }
fsys := os.DirFS(root)

return fs.WalkDir(fsys, ".", func(name string, d fs.DirEntry, err error) error {
    if err != nil { return err }
    if d.IsDir() { return nil }
    logical := path.Clean(name) // 仍然是 FS 逻辑名
    physical := filepath.Join(root, filepath.FromSlash(logical))
    return runTool(physical)
})

这里有两个关键点：path 处理 FS 约定的斜杠路径，filepath 处理当前操作系统的路径；filepath.Join 还承担了根目录与子路径的组合。若下游仍是 FS API，就不要提前转换，继续传 logical。

把输出交给外部工具的四步

第一步，启动时把根目录固定为绝对路径，并明确它只服务于外部边界。第二步，在遍历阶段保留 name 的逻辑语义，必要时用 fs.ValidPath 检查来自其他来源的名字。第三步，转换时使用 filepath.FromSlash，再用 filepath.Join(root, relative) 组装，不手写 “/” 或 “\\”。第四步，把最终物理路径作为一个完整参数传给命令执行层，不把它拼入 shell 字符串。

如果工具其实支持从标准输入读取文件内容，优先传内容或使用 FS 读取结果，能减少平台路径差异。只有工具明确要求磁盘文件名时，才做物理路径转换；这条判断能让迁移后的代码更容易测试。

迁移后的回归检查

至少覆盖四组场景：根目录下的单文件、两层以上子目录、空目录和包含空格的目录名。测试应分别断言 FS API 收到的是逻辑名、外部工具收到的是以固定根开头的物理路径。再在 Windows 或交叉编译环境验证分隔符，不要把 Unix 的 /tmp 样例当作跨平台证明。

最后检查错误返回：WalkDir 回调收到 err 时应原样返回或包装后保留原因；不要因为转换失败而继续把半成品路径交给工具。这样，os.File 到 io/fs.FS 的迁移就只改变遍历抽象，不会悄悄改变外部命令的输入。

相关问题

WalkDir 的 name 能直接传给 fs.ReadFile 吗？

可以，只要它仍属于同一个 FS，且是合法的相对逻辑路径；不要把它当作操作系统绝对路径。

什么时候必须使用 filepath？

当目标 API 明确要求当前操作系统的文件名时，例如外部命令、os.Stat 或 os.Open，在边界处转换。