Go filepath.Rel 计算相对路径的跨平台用法

filepath.Rel(basePath, targPath) 用来计算“从 basePath 到 targPath 怎么走”。跨平台使用时最重要的不是手工替换斜杠，而是让两个输入都遵循当前运行操作系统的文件路径语义，并检查返回错误。绝对路径与相对路径混用、Windows 不同卷名、或计算过程必须依赖当前工作目录时，都可能失败。

它做的是词法路径计算：会清理 .、.. 和重复分隔符，但不会访问文件系统，也不会解析符号链接。返回值适合继续传给本机文件 API；若要写进清单、缓存键或跨平台协议，再在明确的格式边界调用 filepath.ToSlash。

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

变化一句话：不要自己切字符串

我第一次在打包工具里处理相对路径时，用的是“确认目标以前缀开头，再裁掉前缀”的办法。它在简单 Unix 路径上看起来没问题，一到 Windows 盘符、大小写与反斜杠场景就开始出现边角错误。

迁移到 filepath.Rel 后，代码的变化可以浓缩成一句话：从字符串前缀逻辑，改为操作系统路径语义。标准库给出的契约是，若调用成功，把返回的相对路径与 basePath 通过 filepath.Join 组合，会得到一个与 targPath 词法等价的路径。

rel, err := filepath.Rel(basePath, targetPath)
if err != nil {
    return fmt.Errorf("计算相对路径: %w", err) // 保留标准库的具体失败原因。
}
fmt.Println(rel) // 输出使用当前操作系统的路径分隔符。

相同路径的结果是 .；目标位于基准目录下时，结果通常是子路径；目标位于旁边或上层时，结果可能包含 ..。所以“结果里出现 ..”本身不是错误，而是普通相对路径表达。

为什么跨平台代码容易写错

path/filepath 专门处理操作系统文件名：Unix 通常使用 /，Windows 使用 \，并额外存在盘符与 UNC 卷名。filepath.Rel 会先清理输入，再比较绝对性、卷名和路径元素。

这里还有一个容易被忽略的边界：filepath.Rel 按程序实际运行的平台解释字符串。不要指望 Linux 上的 filepath.Rel 自动理解任意 Windows 路径字符串；反过来也一样。需要离线处理另一种系统的路径格式时，应使用明确支持该格式的解析器，或者在目标平台执行对应测试。

封装一个可复用的 RelativePath

工程代码通常还要决定是否输出统一的正斜杠。下面的封装先把两个输入变成绝对路径，从而避免绝对与相对混用；计算成功后，仅在调用者明确要求“可移植文本”时执行 ToSlash。

package relpath

import (
    "fmt"
    "path/filepath"
)

type Options struct {
    PortableSlash bool // true 表示输出适合清单或缓存键的正斜杠文本。
}

func RelativePath(basePath, targetPath string, opt Options) (string, error) {
    baseAbs, err := filepath.Abs(basePath)
    if err != nil {
        return "", fmt.Errorf("解析基准路径 %q: %w", basePath, err)
    }

    targetAbs, err := filepath.Abs(targetPath)
    if err != nil {
        return "", fmt.Errorf("解析目标路径 %q: %w", targetPath, err)
    }

    rel, err := filepath.Rel(baseAbs, targetAbs)
    if err != nil {
        return "", fmt.Errorf("从 %q 到 %q 计算相对路径: %w", baseAbs, targetAbs, err)
    }

    if opt.PortableSlash {
        rel = filepath.ToSlash(rel) // 只在文本协议边界统一为正斜杠。
    }
    return rel, nil
}

filepath.Abs 会在输入不是绝对路径时结合当前工作目录，因此要把“当前目录参与计算”当成明确设计，而不是隐藏副作用。对于构建工具，我更倾向于让调用方传入稳定的工作区根目录，并在进程启动时只解析一次。

调用示例：

rel, err := relpath.RelativePath(
    filepath.Join("workspace", "assets"),
    filepath.Join("workspace", "assets", "icons", "save.png"),
    relpath.Options{PortableSlash: true},
)
if err != nil {
    log.Fatal(err) // 不忽略不同卷或绝对性问题。
}
fmt.Println(rel) // 清单格式中得到 icons/save.png。

对旧代码的影响：三类常见误区

误区一：用 strings.TrimPrefix 计算相对路径

字符串前缀并不等于路径元素前缀。比如 /data/app 与 /data/application 共享字符串前缀，却不是父子目录。大小写、清理后的 .、重复分隔符和 Windows 卷名还会继续放大问题。

// 不推荐：字符串裁剪不理解路径元素边界。
rel := strings.TrimPrefix(targetPath, basePath)

// 推荐：让标准库按当前平台的文件路径规则计算。
rel, err := filepath.Rel(basePath, targetPath)
if err != nil {
    return err
}

误区二：把不同盘符当成“多写几个 ..”

在 Windows 上，从 C: 卷无法用普通相对路径跳到 D: 卷。filepath.Rel 对不同卷返回错误是正确行为，不应通过丢弃错误、拼接 .. 来伪造结果。此时输出模型应允许保留绝对目标路径，或者把资源复制到同一工作区根下。

误区三：把 Rel 当成目录逃逸防护

filepath.Rel 是词法计算，不解析符号链接，也不负责安全打开文件。仅检查结果是否以 .. 开头，可以处理一部分纯文本场景，却挡不住文件系统中的符号链接变化。

如果需求是“只允许在某个根目录内打开不可信文件名”，应使用面向访问边界的 API，例如 os.OpenInRoot 或 os.Root，而不是把 Rel 当成完整安全沙箱。

官方安全说明：https://go.dev/blog/osroot

迁移建议：文件路径与可移植文本分层

我在跨平台工具里最稳定的做法，是把“本机文件系统路径”和“可移植文本”分成两层：访问磁盘时始终使用 filepath 产生的原生路径；只有写入 JSON 清单、归档索引、缓存键或远程协议时，才显式转换为正斜杠。

• 访问文件：保留 filepath.Rel 返回的原生分隔符，用 filepath.Join 组合。
• 写清单：协议规定使用 / 时，对相对结果调用 filepath.ToSlash。
• 读取清单：如果字段遵循 io/fs 的有效路径规则，可用 filepath.Localize 转为本机路径并处理错误。
• 处理 URL：不要把 URL 当成本机文件名交给 filepath；URL 有自己的路径与转义规则。

这一分层也解释了为什么不应在整个项目里无条件把 \ 替换成 /。转换应发生在格式协议明确的边界，不能改变本机文件 API 所需的路径语义。

最小验证：表驱动测试覆盖关键边界

跨平台测试不要硬编码某个系统的 /tmp 或 C:\。用 t.TempDir 和 filepath.Join 构造路径，测试代码才能跟随运行平台自动选择规则。

package relpath

import (
    "path/filepath"
    "testing"
)

func TestRelativePath(t *testing.T) {
    root := t.TempDir() // 使用当前平台真实有效的临时根目录。
    base := filepath.Join(root, "project", "assets")

    tests := []struct {
        name   string
        target string
        want   string
    }{
        {
            name:   "同一目录",
            target: base,
            want:   ".",
        },
        {
            name:   "子目录文件",
            target: filepath.Join(base, "icons", "save.png"),
            want:   filepath.Join("icons", "save.png"),
        },
        {
            name:   "相邻目录",
            target: filepath.Join(root, "project", "docs", "guide.md"),
            want:   filepath.Join("..", "docs", "guide.md"),
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got, err := filepath.Rel(base, tt.target)
            if err != nil {
                t.Fatalf("Rel 返回错误: %v", err)
            }
            if got != tt.want {
                t.Fatalf("Rel=%q，期望 %q", got, tt.want)
            }

            // 回拼后比较 Clean 结果，验证词法等价关系。
            if filepath.Clean(filepath.Join(base, got)) != filepath.Clean(tt.target) {
                t.Fatalf("回拼路径与目标不等价: %q", got)
            }
        })
    }
}

Windows 不同卷的错误需要在 Windows 环境单独覆盖，因为 Unix 没有相同的卷名语义。持续集成如果支持多个操作系统，可以为 Windows 增加一个使用两个可用卷的条件测试；没有第二个卷时应跳过，而不是伪造路径断言。

常见问题

filepath.Rel 会检查目标文件是否存在吗？不会。它是词法操作，不访问文件系统。需要确认存在性时再调用 os.Stat 等文件 API。

Rel 会解析符号链接吗？不会。如果业务比较的是符号链接解析后的真实位置，需要先明确是否适合调用 filepath.EvalSymlinks；安全敏感场景还要考虑检查与使用之间的竞态。

能把返回值直接写进 JSON 吗？可以，但跨平台共享的 JSON 最好先定义分隔符协议。若约定正斜杠，就在写入边界调用 filepath.ToSlash。

结果是 .. 是否代表失败？不是。它只表示目标位于基准目录的父级方向。如果业务禁止越过根目录，应单独定义并实现访问策略，不能把所有含 .. 的合法相对路径混为错误。

什么时候不该用 filepath.Rel？处理 URL、模块导入路径、归档内部路径或另一操作系统的离线路径文本时，不要默认套用本机文件路径规则；先按对应格式选择专用解析方式。