Go filepath.Localize 怎么把 fs.ValidPath 转成本地路径

接收 embed.FS、fs.Sub 或其他 io/fs.FS 的文件名时，输入通常是统一的斜线格式；真正打开本地文件却要遵守当前操作系统的路径规则。Go 1.23 的 filepath.Localize 就是这个边界转换：先要求输入满足 fs.ValidPath，再返回本地路径；如果当前系统无法表示它，就返回错误。

先分清三种路径：FS 名称、本地路径和普通字符串

io/fs 规定路径名是 UTF-8、非根路径、用 / 分段；除了根目录特殊值 .，不能出现空段、. 或 ..。因此 assets/app.css 是合格的 FS 名称，而 /assets/app.css、assets/../app.css 都不是。

filepath.Localize 的输入契约正是 fs.ValidPath。在 Unix 上，assets/app.css 通常仍会得到斜线路径；在 Windows 上，它会被转换成操作系统使用的分隔符。这里的关键不是“把字符换一下”，而是把跨平台 FS 命名空间交给本地文件系统前再检查一遍。

推荐写法：先保留原名，再处理两类错误

工程代码里我更愿意把原始 FS 名称和转换后的本地路径分开保存。这样日志能指出是输入格式不对，还是目标平台不接受某个字符；不要先 Clean 再偷偷改变用户传入的语义。

package main

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

func localPath(name string) (string, error) {
    // 先按 io/fs 的统一规则拒绝绝对路径、点段和空路径。
    if !fs.ValidPath(name) {
        return "", fmt.Errorf("invalid fs path %q", name)
    }

    // Localize 负责当前操作系统的分隔符和可表示性检查。
    local, err := filepath.Localize(name)
    if err != nil {
        return "", fmt.Errorf("localize %q: %w", name, err)
    }
    return local, nil
}

func main() {
    // 这个示例只演示转换边界，不假定目标文件已经存在。
    local, err := localPath("assets/app.css")
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(local)
}

这里的两次判断看起来有些重复，但它们的职责不同：ValidPath 能给调用方一个明确的 FS 语法结论，Localize 再处理操作系统表示能力。若你不需要区分错误原因，也可以直接调用 Localize，但仍要检查返回的 error。

Windows 反斜线是最容易踩到的边界

fs.ValidPath("a\\b") 在统一 FS 规则下可以返回真，因为反斜线不是 FS 的分隔符；可是在 Windows 中反斜线是本地路径分隔符，不能同时作为文件名字符保留下来，所以 filepath.Localize("a\\b") 会报错。这个差异正是不能用字符串替换替代 Localize 的原因。

同样，fs.ValidPath 接受的冒号并不意味着每个平台都能把它当成普通文件名。实际落盘前应把 Localize 的错误视为“当前平台无法表示”，交给上层选择改名、跳过或提示用户，而不是调用 filepath.Clean 强行修正。

Localize、FromSlash 和 Join 怎么选

一个实用判断是：只要字符串来自 FS 命名空间，就先按 FS 规则处理；只要它已经是本地路径，就不要再把它当作 FS 名称。Localize 成功后仍只是路径字符串，不代表文件存在，也不等于已经完成权限、符号链接或业务目录检查。

相关问题

filepath.Localize 是从哪个 Go 版本开始提供的？

它在 Go 1.23 加入 path/filepath，用于安全地把斜线分隔路径转换为操作系统路径。

Localize 能把绝对路径转换成相对路径吗？

不能。绝对路径不满足 fs.ValidPath，应在进入 FS 边界前重新设计输入或单独走本地路径流程。

调用 Localize 成功后还要检查 IsLocal 吗？

通常不需要重复检查，因为官方契约保证返回路径是 local；但仍要根据业务检查文件是否存在、是否允许访问以及符号链接行为。

FromSlash 能代替 Localize 吗？

不能。FromSlash 只替换分隔符，不会拒绝 ..、绝对路径或当前平台无法表示的名称。