Go filepath.IsLocal 怎么筛除绝对路径和逃逸路径

当接口参数、压缩包条目或配置文件里带着相对路径时，可以先用 filepath.IsLocal 做一道词法过滤。它会拒绝绝对路径、空字符串、会逃出当前目录的路径；在 Windows 上还会拒绝 NUL 这类保留名。判断通过后再调用 filepath.Join(base, name)，结果在词法上会留在 base 之内。

IsLocal 判断的四个词法条件

filepath.IsLocal(path) 从 Go 1.20 开始提供。官方契约包含四个核心条件：路径位于求值目录的子树中、不是绝对路径、不是空字符串，并且在 Windows 上不是保留设备名。由于判断只分析字符串，同一段代码会按照当前操作系统的路径语法工作。

它比单独调用 filepath.IsAbs 更适合过滤外部输入。IsAbs 只能发现绝对路径，却不会替你判断 ../../secret.txt 这种相对形式是否向上逃逸；IsLocal 会把这两个问题一起处理。

最小配方：通过后再和基准目录拼接

下面的函数适合“用户只能选择基准目录内的相对文件”这类场景。拒绝时保留原始输入，便于上层记录日志；通过后只返回拼接结果，不提前声称文件存在。

package main

import (
    "fmt"
    "path/filepath"
)

func joinLocal(base, name string) (string, error) {
    // IsLocal 同时排除绝对路径、空路径和词法上的目录逃逸。
    if !filepath.IsLocal(name) {
        return "", fmt.Errorf("unsafe local path %q", name)
    }

    // 官方契约保证：判断通过后与 base 拼接，词法结果仍在 base 内。
    return filepath.Join(base, name), nil
}

func main() {
    // 这里只演示路径边界，不访问真实文件系统。
    path, err := joinLocal("uploads", "avatars/user.png")
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(path)
}

不要先用 filepath.Clean 把输入改写后再悄悄接受。更清晰的做法是先用原始输入调用 IsLocal，明确告诉调用者输入是否满足约束；通过后由 Join 负责规范化拼接。

不是所有带点段的路径都会被拒绝

IsLocal 关注清理后的路径会不会离开当前目录。因此 a/../b.txt 清理后仍是 b.txt，通常可以通过；../b.txt 和 a/../../b.txt 清理后仍需要向上越界，会被拒绝。若业务规则要求“任何 .. 都不允许”，还应额外逐段检查，而不能把这个更严格的规则归给 IsLocal。

Windows 还要注意卷名和保留设备名

路径语法依赖操作系统。Windows 上的盘符路径、UNC 路径和根路径都会被当作非本地输入；NUL、CON 等保留名也不满足 IsLocal。相同字符串在 Unix 和 Windows 上可能得到不同结果，所以跨平台项目应在目标系统的 CI 中覆盖对应测试，而不是把 Unix 结果写死成所有平台的结论。

如果输入来自 URL 或 io/fs 的统一斜线路径，先判断它属于哪一种命名空间。filepath.IsLocal 处理的是操作系统本地路径；把 io/fs 名称转换成本地路径时，应使用 filepath.Localize，不要把两种契约混在一起。

词法安全不等于文件系统安全

IsLocal 不读取磁盘，因此看不到符号链接。例如 uploads/current/report.txt 在字符串上完全本地，但如果 uploads/current 是指向基准目录之外的符号链接，后续普通文件打开仍可能越过预期边界。它也不负责判断用户是否有权访问某个本地文件。

对于真正的文件访问边界，新版 Go 可以用 os.OpenRoot 打开一个目录根，再通过 Root.Open、Root.ReadFile 等方法访问其中的名称。os.Root 会把文件系统操作约束在根目录内，适合上传目录、解压目录和多租户文件区；业务层仍要继续检查允许的扩展名、文件大小和访问权限。

用表驱动测试锁住允许与拒绝规则

路径过滤很容易因为业务规则变化而回退。下面的测试只固定平台无关的核心样例；Windows 保留名和盘符样例应放进带平台条件的测试文件。

package localpath

import (
    "path/filepath"
    "testing"
)

func TestIsLocalCoreCases(t *testing.T) {
    cases := []struct {
        name string
        want bool
    }{
        // 普通相对路径应当被接受。
        {"docs/readme.txt", true},
        // 内部点段清理后没有越界，IsLocal 可以接受。
        {"a/../b.txt", true},
        // 下面三类输入分别覆盖向上逃逸、绝对路径和空路径。
        {"../secret.txt", false},
        {string(filepath.Separator) + "etc", false},
        {"", false},
    }

    for _, tc := range cases {
        // 每个失败用例都打印原始路径，方便定位规则变化。
        if got := filepath.IsLocal(tc.name); got != tc.want {
            t.Fatalf("IsLocal(%q) = %v, want %v", tc.name, got, tc.want)
        }
    }
}

如果你的规则比标准库更严格，例如禁止任何点段、只允许单层文件名，或只允许固定后缀，就在 IsLocal 通过后继续叠加业务检查。这样标准库负责跨平台词法边界，业务代码负责项目自己的允许列表。

相关问题

filepath.IsLocal 会检查文件是否存在吗？

不会。它是纯词法操作，不访问文件系统；文件存在性、权限和符号链接都要在后续文件操作中处理。

IsLocal 能完全防止 Zip Slip 吗？

它能过滤绝对路径和词法逃逸，是解压条目校验的重要一层，但还应控制符号链接、目标根目录、覆盖策略和文件类型。需要真实目录约束时优先使用 os.Root。

可以用 strings.Contains(path, "..") 代替吗？

不建议。字符串包含判断会误伤普通文件名，也不理解平台分隔符、绝对路径和 Windows 保留名；filepath.IsLocal 才按目标系统的路径语法判断。

IsLocal 通过后还要调用 filepath.Clean 吗？

通常直接调用 filepath.Join(base, path) 即可，因为 Join 会清理结果。若只需要规范化单个路径，可以单独 Clean，但不要把 Clean 当作安全校验。