Go filepath.IsLocal 怎么挡住路径穿越：本地路径语义与清理边界

文件下载接口最容易被忽略的输入，往往不是文件名，而是调用方传来的相对路径。把 ../config.yaml 直接交给 filepath.Join，并不能替代边界判断。Go 的 filepath.IsLocal 适合放在入口，先拦截绝对路径、空路径和会走出当前目录的路径，再决定是否继续拼接。

把 filepath.IsLocal 当作词法层的第一道门：通过后用 filepath.Join 生成目标路径；如果目录里允许符号链接，再用 filepath.EvalSymlinks 复核真实位置。

文件下载接口为什么会把路径当成安全输入

一个常见接口是 GET /download?name=reports/2026-08.csv。开发者先取参数，再写出 filepath.Join(uploadRoot, name)，本意是把文件限制在 uploadRoot。问题在于，Join 会清理路径，它解决的是路径表达式的拼接，不是授权。

例如用户传入 ../secrets/app.env，拼接结果可能落到 uploadRoot 的上级目录。输入路径的“看起来像文件名”不能作为判断依据，边界应该在读取文件之前明确写出来。

先用 filepath.IsLocal 做入口判定

IsLocal 的判定是词法分析：它要求路径不是空字符串、不是绝对路径，并且在当前路径语义下不会走出所在子树。Windows 下还会排除保留名。它不会检查文件是否存在，也不会解析符号链接。

func localName(name string) (string, error) {
	if !filepath.IsLocal(name) {
		return "", fmt.Errorf("path is not local")
	}
	return name, nil
}

这里的 允许 只代表输入通过词法门槛，拒绝 代表请求应该在打开文件之前结束。不要把用户路径先 Clean 再判断：清理后的字符串可能已经隐藏了原始输入试图回退目录的事实。

通过检查后，用 filepath.Join 形成目标路径

入口判定通过后，使用固定的服务端根目录和用户相对路径生成目标路径。Join 会按操作系统规则处理分隔符并清理结果，调用方不需要自己拼接 "/" 或 "\\"。

func downloadPath(root, name string) (string, error) {
	if !filepath.IsLocal(name) {
		return "", fmt.Errorf("invalid local path")
	}
	target := filepath.Join(root, name)
	return target, nil
}

这段代码适合“根目录下的普通文件”场景。根目录本身仍应由服务端配置提供，不能让请求参数决定。对于需要权限控制的系统，还要在这里叠加租户、用户和文件记录的授权判断。

符号链接会让词法安全和真实位置出现差异

如果 root 内允许创建符号链接，reports/latest 可能指向根目录外。此时 IsLocal 返回 true 并不矛盾：它只看路径字符串，并不知道磁盘上的链接关系。

func resolvedPath(root, name string) (string, error) {
	if !filepath.IsLocal(name) {
		return "", fmt.Errorf("path is not local")
	}
	target := filepath.Join(root, name)
	resolved, err := filepath.EvalSymlinks(target)
	if err != nil {
		return "", err
	}
	return resolved, nil
}

复核结果必须再和允许目录比较，不能只因为 EvalSymlinks 成功就放行。生产代码通常会把 root 和 resolved 都转成绝对路径，然后用 filepath.Rel 判断结果是否仍在 root 子树中；比较时要考虑路径分隔符和边界，避免把 /srv/files2 误认成 /srv/files 的子目录。只有确认解析后的目标仍是允许目录内的真实文件，才进入后续读取。

三个容易误用的边界

• 把 IsLocal 当权限校验：它不认识登录用户、租户和文件 ACL，只解决路径形状。
• 只判断 IsAbs：相对路径也可能包含 ..，还可能是空字符串或 Windows 保留名。
• 只比较字符串前缀：目录名存在同名前缀时会误放行，优先用 Rel 得到相对关系并检查首段。

相关问题

filepath.IsLocal 能防住符号链接吗？

不能。官方文档明确说明它是纯词法操作，不考虑文件系统里的符号链接；允许链接的目录需要额外解析真实路径。

filepath.Clean 能替代 filepath.IsLocal 吗？

不能。Clean 只做字符串清理，适合得到规范形式；它不会表达“这个输入是否允许被接受”的策略。

为什么不直接用 filepath.IsAbs？

IsAbs 只能识别绝对路径，不能覆盖空路径、父目录回退和 Windows 保留名等边界。

IsLocal 通过后还需要授权判断吗？

需要。它不判断当前用户是否有权访问文件，也不处理租户隔离、文件状态和业务层的下载权限。

把路径安全拆成两层检查

对普通文件目录，推荐的最小顺序是：先用 filepath.IsLocal 拦截输入，再用 filepath.Join 生成目标；目录可能被写入链接时，再用 filepath.EvalSymlinks 和 filepath.Rel 验证真实位置，最后叠加业务授权。这样每个函数负责一个边界，测试也能分别覆盖词法拒绝、正常文件、链接越界和权限不足。