Go filepath.Localize 怎样转换 slash 路径

在 Go 程序里，资源包、归档文件和 io/fs 接口通常使用统一的 slash（/）路径；真正访问本地文件系统时，又必须遵守当前操作系统的路径分隔符。filepath.Localize 就是这两种表示之间的安全转换入口。

官方文档：https://pkg.go.dev/path/filepath#Localize

filepath.Localize 接收一个符合 io/fs.ValidPath 规则的 slash 分隔路径，返回当前系统可表示的本地路径；输入不合法或无法在当前系统表示时，会返回错误。它不是无条件地把字符替换成反斜杠。

先确认输入路径属于 fs.ValidPath

Localize 的输入契约比“字符串里有斜杠”严格：路径应是 slash 分隔的相对路径，不能把空字符串、绝对路径或含有反斜杠的任意用户输入直接当成合格参数。先把来源边界想清楚，后面的错误才有意义。

package main

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

func main() {
    inputs := []string{"assets/logo.svg", "./assets/logo.svg", "assets\\logo.svg"}
    for _, input := range inputs {
        // 先检查 slash 路径契约，再交给 Localize 做平台转换。
        fmt.Printf("input=%q valid=%v\n", input, fs.ValidPath(input))
        local, err := filepath.Localize(input)
        if err != nil {
            // 错误保留给调用方，不能把非法路径静默改写掉。
            fmt.Printf("localize error: %v\n", err)
            continue
        }
        fmt.Printf("local=%q\n", local)
    }
}

这段示例的重点不是在当前机器上展示某个固定输出，而是观察判断顺序：输入先通过 fs.ValidPath，再调用转换函数；一旦出现错误，保留错误分支，不用“替换几个字符”掩盖来源问题。

调用 Localize 时要同时处理结果和 error

最小调用只有一个字符串参数和两个返回值。成功时，返回值使用当前系统的本地分隔符；失败时，错误表示这个 slash 路径无法被当前系统表示。Windows 上尤其要注意，反斜杠本身是分隔符，不能像普通文件名字符那样随意嵌入路径段。

func localPath(slashPath string) (string, error) {
    // Localize 同时完成输入约束和本地表示转换。
    local, err := filepath.Localize(slashPath)
    if err != nil {
        return "", fmt.Errorf("localize %q: %w", slashPath, err)
    }
    // 返回本地路径，不在这里继续拼接未经处理的用户输入。
    return local, nil
}

工程代码里建议把错误向上包装并带上原始输入，日志或上层提示就能区分“资源不存在”和“路径本身不能转换”。Localize 只负责路径表示，不负责创建目录、读取文件或判断目标是否已经存在。

Localize、FromSlash 和 ToSlash 不要混用

三个函数看起来都和 slash 有关，但职责不同：Localize 面向符合 io/fs 约定的路径并返回错误；FromSlash 只是把每个 slash 替换为系统分隔符，不返回错误；ToSlash 则把本地分隔符转换为 slash，适合生成跨平台的逻辑路径。

用边界样例判断转换是否正确

排查“路径转换后打不开”时，可以按四个问题检查：输入是否为空或绝对路径；是否混入了反斜杠；是否包含当前系统不能作为文件名的字符；调用方是否把转换结果误当成已经存在的文件。Localize 的成功只说明“可以用本地路径表示”，并不承诺文件存在。

如果数据来自 io/fs、嵌入文件或归档条目，保留 slash 形式作为逻辑名称，真正落到操作系统 API 前再 Localize。反过来，如果数据已经是本地路径，不要为了“统一”再次调用 Localize；需要跨平台传输时使用 ToSlash。

相关问题

Localize 会创建目录吗？不会，它只转换路径表示。

Localize 和 FromSlash 的最大区别是什么？Localize 遵守 fs.ValidPath 并可能返回错误，FromSlash 只做分隔符替换。

为什么不能直接用 strings.ReplaceAll？字符串替换无法表达平台非法路径、输入契约和错误边界，容易把无效路径伪装成有效路径。