Go filepath.IsLocal 怎样在接收用户路径前拒绝绝对路径

如果接口接收一个文件名，再把它拼到工作目录下，最先要拦住的不是“文件是否存在”，而是输入本身是不是一个本地相对路径。Go 1.20 加入的 filepath.IsLocal 会用词法分析判断路径是否非空、非绝对、没有越出当前路径子树；在 Windows 上还会排除类似 NUL 的保留名。用它做第一道门禁，就能避免把用户传入的绝对路径直接带入后续文件操作。

先把用户路径和工作目录分开

常见写法是直接把用户字符串传给 filepath.Join。问题在于，拼接函数负责组合路径，不负责替你定义“用户只能在工作目录内选择文件”的规则。更稳妥的模型是：base 是服务端已经确定的目录，input 只是用户想访问的相对名称；先检查 input，再把它交给 Join。

package main

import (
    "errors"
    "fmt"
    "path/filepath"
)

var errUnacceptablePath = errors.New("path must be local")

func resolveUserPath(base, input string) (string, error) {
    // IsLocal 只检查路径的词法边界，不读取磁盘，也不跟随符号链接。
    if !filepath.IsLocal(input) {
        return "", fmt.Errorf("%w: %q", errUnacceptablePath, input)
    }
    // 通过词法门禁后再拼接，避免把绝对路径当成新的根目录使用。
    return filepath.Join(base, input), nil
}

func main() {
    // 这些输入代表相对文件、绝对文件、空值和父目录跳转意图。
    samples := []string{"reports/today.csv", "/etc/hosts", "", "../secret.txt"}
    for _, input := range samples {
        path, err := resolveUserPath("/srv/app-data", input)
        if err != nil {
            fmt.Printf("拒绝 %q: %v\n", input, err)
            continue
        }
        fmt.Printf("允许 %q -> %q\n", input, path)
    }
}

这里的关键顺序只有两步：先让 IsLocal 判断 input，再调用 Join。官方文档说明，当它返回 true 时，Join(base, input) 会得到仍然位于 base 下的路径，Clean(input) 也不会留下 .. 路径元素。这个结论是词法层面的，不等于磁盘上最终解析到的对象一定没有符号链接。

哪些输入应该直接拒绝

排障时不要只测试一个以斜杠开头的字符串。IsLocal 关注的是“路径是否属于当前目录子树”这一整体性质，空字符串也会返回 false；包含父目录元素、绝对路径以及 Windows 的盘符、UNC 或保留设备名，都应按目标操作系统的规则理解。

不要把 filepath.IsAbs 当成完全等价的替代品。IsAbs 只回答“是不是绝对路径”，而 IsLocal 还会把空输入、父目录边界以及平台保留名纳入判断。两者的目标不同：前者适合展示路径属性，后者更适合做“用户路径能否进入本地工作树”的词法门禁。

IsLocal 通过后还要做什么

最容易被误解的一点是：IsLocal 不会访问磁盘。它不会确认文件存在、不会检查权限、不会判断路径是文件还是目录，也不会解析符号链接。因此通过检查后仍然要让真实文件操作返回错误，并按业务决定是返回 404、参数错误还是内部错误。

func openReport(base, input string) (*os.File, error) {
    // 先拒绝非本地词法路径，再打开最终拼接结果。
    if !filepath.IsLocal(input) {
        return nil, fmt.Errorf("invalid report path %q", input)
    }
    fullPath := filepath.Join(base, input)
    // Open 的错误仍然有效：文件可能不存在、无权限或不是普通文件。
    file, err := os.Open(fullPath)
    if err != nil {
        return nil, fmt.Errorf("open report: %w", err)
    }
    return file, nil
}

如果你的威胁模型包含符号链接，词法判断还不够。需要根据部署环境选择更严格的目录句柄、平台能力或 os.Root 等方案，并明确处理链接和竞态；不能因为 IsLocal 返回 true，就宣称最终访问对象一定不会跳出工作目录。

用跨平台测试把规则固定下来

路径规则由目标操作系统决定，测试不要只在当前开发机上写一条断言。Unix 至少覆盖普通相对路径、空值、绝对路径和 ..；Windows 再加入盘符、UNC 和保留名。测试的目标不是证明每个文件都能打开，而是固定“哪些输入可以进入下一层”的边界。

func TestResolveUserPath(t *testing.T) {
    // 表格测试只断言词法门禁，文件是否存在交给更高层测试。
    cases := []struct {
        name  string
        input string
        local bool
    }{
        {name: "relative", input: "reports/today.csv", local: true},
        {name: "empty", input: "", local: false},
        {name: "parent", input: "../secret.txt", local: false},
    }
    for _, tc := range cases {
        if got := filepath.IsLocal(tc.input); got != tc.local {
            t.Errorf("IsLocal(%q) = %v, want %v", tc.input, got, tc.local)
        }
    }
}

最终可以把规则记成一张小清单：输入是否非空，是否是本地路径，是否满足扩展名和目录要求，拼接后是否执行了真实打开，以及当前威胁模型是否还需要符号链接级别的约束。这样排查“为什么绝对路径被接受”时，不会把词法判断、业务校验和文件系统错误混在一起。

常见问题

IsLocal 返回 true 就代表文件一定存在吗？

不代表。它只做词法分析；文件存在性、权限和类型仍由后续系统调用判断。

先调用 Clean 再判断可以吗？

不建议把 Clean 当成放行依据。先判断原始用户输入是否满足本地路径规则，再根据需要清理和拼接，避免把越界意图悄悄改写成另一条路径。

IsLocal 能防止符号链接跳出目录吗？

不能。官方说明它不考虑文件系统中的符号链接；涉及不可信路径和强威胁模型时，需要更强的目录边界方案。