fs.ValidPath 与 filepath 路径分隔符的转换

如果路径来自 embed.FS、os.DirFS 或其他 io/fs.FS，不要先把它当成本机字符串处理。io/fs 规定的是统一的斜杠路径，例如 assets/icons/logo.svg；真正要交给本地文件 API 时，再把它转换成当前操作系统能表示的路径。

最稳妥的顺序是：先用 fs.ValidPath 判断虚拟路径，再用 filepath.Localize 做本地化。如果只是调用 filepath.FromSlash，得到的只是分隔符替换，并不代表路径已经满足 io/fs 规则。

官方文档：https://pkg.go.dev/io/fs　https://pkg.go.dev/path/filepath

先区分虚拟路径和本地路径

io/fs 的路径名在所有系统上都使用斜杠分隔，并且是未加根的相对名称。普通文件名可以是 docs/readme.md，根目录用特殊名称 . 表示；开头的 /、结尾的 /、空路径、. 和 .. 路径元素都不符合普通有效路径规则。

这里有一个容易忽略的细节：反斜杠在 io/fs 语义里不是统一的分隔符。fs.ValidPath("a\\b") 在规则层面可以通过，因为它只有一个路径元素；但在 Windows 上，反斜杠又是本地分隔符，后续转换可能无法把它表示成单个文件名。也就是说，“虚拟路径有效”和“当前操作系统可表示”是两个阶段。

用 fs.ValidPath 判断能否交给 FS.Open

fs.ValidPath 判断的是 FS.Open 所使用的名称语法，不检查磁盘上是否存在文件，也不检查权限。把它放在输入边界，可以尽早拒绝绝对路径、目录穿越片段和多余分隔符。

package main

import (
    "fmt"
    "io/fs"
)

func main() {
    candidates := []string{
        ".",                    // 点表示 FS 的根目录。
        "assets/logo.svg",      // 斜杠分隔的普通虚拟路径。
        "/assets/logo.svg",     // 绝对路径不属于 io/fs 名称。
        "assets/../secret.txt", // .. 不能用于绕过虚拟目录边界。
        "assets//logo.svg",     // 空路径元素会让名称无效。
        `assets\\logo.svg`,      // 反斜杠是普通字符，不是 fs 分隔符。
    }

    for _, name := range candidates {
        fmt.Printf("%q -> %t\\n", name, fs.ValidPath(name)) // 这里只报告语法，不访问磁盘。
    }
}

不要把 ValidPath 的返回值理解成“文件可读”。通过校验后仍可能遇到不存在、权限不足或底层实现拒绝访问等错误；它只负责把输入收敛到 io/fs 约定的名称空间。

用 filepath.Localize 转成操作系统路径

当一个已验证的 io/fs 路径需要交给 os.Open、filepath.Join 或其他本地 API 时，优先使用 filepath.Localize。它要求输入先满足 fs.ValidPath，并在路径不能被当前操作系统表示时返回错误；返回值还应当是本地路径。

package main

import (
    "fmt"
    "io/fs"
    "path/filepath"
)

func toLocalPath(name string) (string, error) {
    if !fs.ValidPath(name) {
        return "", fmt.Errorf("invalid fs path %q", name) // 先拒绝绝对路径、点段和空元素。
    }

    local, err := filepath.Localize(name)
    if err != nil {
        return "", fmt.Errorf("localize %q: %w", name, err) // Windows 等系统可能无法表示某些名称。
    }
    return local, nil
}

func main() {
    local, err := toLocalPath("assets/icons/logo.svg")
    if err != nil {
        fmt.Println(err) // 转换失败时不要继续调用本地文件 API。
        return
    }
    fmt.Println(local) // Unix 通常仍是斜杠，Windows 会使用本机分隔符。
}

这个函数没有检查文件是否存在，也没有打开文件。它只完成“名称规则校验”和“本地路径表示”两件事，调用方可以在后续步骤中明确决定是读取、拼接工作目录，还是把路径交给别的本地组件。

为什么不能只调用 filepath.FromSlash

filepath.FromSlash 的职责很窄：把字符串中的斜杠替换为当前系统的路径分隔符。在 Windows 上，a/b 会变成使用反斜杠的本地形式；在 Unix 上通常保持不变。但它不会判断路径是否绝对，不会拒绝 ..，也不会检查空元素。

package main

import (
    "fmt"
    "io/fs"
    "path/filepath"
)

func main() {
    name := "../outside/config.yaml"
    converted := filepath.FromSlash(name) // 只替换分隔符，不能代替路径校验。
    fmt.Println("converted:", converted)
    fmt.Println("valid fs path:", fs.ValidPath(name)) // 这个输入仍然会因 .. 被拒绝。
}

因此，来自归档文件、嵌入资源、HTTP 参数或数据库字段的虚拟名称，不应该直接走 FromSlash 再拼接本地目录。正确的边界是先判断它是否是允许的 io/fs 名称，再根据目标 API 选择 Localize 或继续保持 slash-separated 形式。

把转换边界接到文件访问

如果资源本来就在一个 fs.FS 中，通常不需要先转成本地路径，直接调用 fs.ReadFile(fsys, name) 更符合抽象边界。只有必须调用本地文件 API 时，才做本地化。下面的辅助函数把两种入口区分开：

package main

import (
    "fmt"
    "io/fs"
    "os"
    "path/filepath"
)

func readLocalFile(baseDir, name string) ([]byte, error) {
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("invalid resource name %q", name) // 资源名先过统一的 fs 规则。
    }

    local, err := filepath.Localize(name)
    if err != nil {
        return nil, fmt.Errorf("cannot represent resource %q: %w", name, err) // 跨平台转换失败要显式返回。
    }

    full := filepath.Join(baseDir, local) // 这里只拼接已经本地化的相对名称。
    data, err := os.ReadFile(full)
    if err != nil {
        return nil, fmt.Errorf("read %q: %w", full, err) // 不存在和权限问题留给文件 API 报告。
    }
    return data, nil
}

若 baseDir 还涉及符号链接、权限边界或不可信目录，路径语法校验并不能单独构成安全边界；这属于目录访问策略和文件系统能力的另一层设计。本文只解决虚拟路径到本地路径的表示转换。

一张表记住三个 API 的分工

可以把整个过程记成一句话：fs.ValidPath 负责“能不能作为 FS 名称”，filepath.Localize 负责“能不能在本机表示”，真正的 Open/ReadFile 再负责“文件能不能访问”。

常见问题

fs.ValidPath(".") 为什么是有效的？

在 io/fs 中，. 是根目录的特殊名称。它和包含普通点段的 a/./b 不是一回事，后者不符合有效路径规则。

Unix 上能用反斜杠，Windows 上为什么还可能失败？

因为 io/fs 把反斜杠当作普通字符，而 Windows 把它当作本地分隔符。filepath.Localize 会拒绝无法同时满足两套语义的输入。

资源在 embed.FS 中时还需要 Localize 吗？

通常不需要。只要调用方继续使用 fs.FS 抽象，就保持斜杠路径并直接调用 fs.ReadFile；只有跨到本地文件 API 时才转换。