Go filepath.IsLocal 与 Clean 有什么区别

Go 的 filepath.Clean 和 filepath.IsLocal 都只做词法层面的路径处理，但目标完全不同：Clean 把路径整理成更短、更规范的写法；IsLocal 判断路径是否为空间隔离意义上的本地相对路径。需要把用户输入拼到固定目录时，不能只调用 Clean，应先用 IsLocal 判断，再用 Join 组合。

一、先把两个函数的职责分开

Clean 会合并重复分隔符、去掉 .、消解中间的 ..，并把空结果变成 .。它的返回值仍然是一个字符串，例如在 Unix 上，filepath.Clean("a/../b") 得到 "b"，而 filepath.Clean("../../b") 仍然可能得到 "../../b"。它不会告诉调用方“这个路径是否可以接受”。

IsLocal 从 Go 1.20 起提供本地路径判定。返回 true 的路径必须不是空字符串、不是绝对路径、不能通过 .. 走出当前目录树；在 Windows 上还不能是 NUL 这类保留名。它同样不访问磁盘，因此判断的是路径表达式，而不是文件是否存在。

二、用边界输入看出真正区别

因此，“先 Clean 再判断是否本地”并不是把两个函数等价使用。Clean 可能把输入整理得更好看，但它不会把 ../today 变成安全输入；相反，IsLocal 的价值正是把这类路径直接判为不接受。

三、拼接用户路径时采用先判定、后组合

当固定目录是应用自己的缓存目录，而用户只允许提供相对文件名时，可以把边界写成一个小函数。示例中的错误信息只用于帮助调用方定位输入问题，不代表已经访问了磁盘。

package safejoin

import (
    "errors"
    "path/filepath"
)

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

func Under(base, input string) (string, error) {
    // 先拒绝空值、绝对路径和词法上的 .. 越界路径。
    if !filepath.IsLocal(input) {
        return "", ErrNotLocalPath
    }
    // Join 会按当前操作系统的分隔符拼接，并再次做 Clean。
    return filepath.Join(base, input), nil
}

这里不需要先调用 Clean：Join 本身会清理组合结果，而 IsLocal 先保证输入没有词法越界。若业务允许用户输入“带有多余 ./ 的相对路径”，它仍然可以通过；若业务还要求固定扩展名、禁止空文件名或限制目录层级，应在 IsLocal 通过后继续增加业务规则。

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

官方文档特别说明，IsLocal 只做词法分析，不考虑符号链接。如果 base/user 是一个指向其他目录的符号链接，单靠 IsLocal("user/file.txt") 不能证明最终打开的对象仍位于物理上的 base 内。涉及不可信目录、上传文件或敏感配置时，还要结合目录权限、符号链接解析、打开文件时的系统约束和审计策略。

另外，filepath 依据目标操作系统解释分隔符。处理 URL、归档内部路径或协议字段时，应优先考虑 path 或 io/fs 的路径规则，不能把跨平台字符串一律交给 filepath。

相关问题

Clean 能替代 IsLocal 吗？

不能。Clean 只负责规范化字符串，不负责给出可接受性判断；需要限制用户路径时，应明确调用 IsLocal。

IsLocal 返回 true 后还要判断文件是否存在吗？

要。IsLocal 不访问文件系统，只说明路径表达式满足词法边界；文件存在性、权限、符号链接和类型仍需按业务检查。