Go filepath.IsLocal 怎样筛出不安全的外部路径

处理用户上传的文件名、导出路径或压缩包内条目时，最先要回答的不是“文件是否存在”，而是“这个字符串能不能作为当前目录下的相对路径”。Go 的 filepath.IsLocal 适合做这一步筛选：返回 true 表示路径在词法上是本地的，返回 false 则应当拒绝或转入单独的外部路径处理分支。

它只做词法分析，不访问文件系统，也不解析符号链接。因此，IsLocal 能挡住绝对路径、空路径、越过父目录的路径以及 Windows 保留名，却不能单独承担“文件一定不会逃出沙箱”的全部责任。下面按这个边界写一个可直接复用的入口。

先理解 filepath.IsLocal 到底筛什么

官方文档把判断条件限定得很清楚：路径不能是绝对路径，不能是空字符串，清理后不能越过当前目录子树；在 Windows 上还不能是 NUL 这类保留名。只要返回 true，将它交给 filepath.Join(base, path)，结果在词法上仍位于 base 下。

这里的“安全”要理解成“适合作为相对路径输入”，而不是“已经打开文件并完成权限检查”。例如 reports/2026.txt 是本地路径，../secret.txt 不是；/var/tmp/a.txt 和空字符串也不是。

用一组输入看出返回值差异

先不要把 Clean 的结果当成校验结果。Clean 会做词法归一化，例如把 a/../b 变成 b；而 IsLocal 关注的是原路径是否带有越过当前子树的意图。两者职责不同，输入应直接交给 IsLocal。

package main

import (
	"fmt"
	"path/filepath"
)

func main() {
	paths := []string{
		"reports/2026.txt",
		"./reports/2026.txt",
		"../secret.txt",
		"reports/../../secret.txt",
		"/var/tmp/export.txt",
		"",
	}

	for _, path := range paths {
		// IsLocal 只分析路径字符串，不要求目标文件已经存在。
		fmt.Printf("%-28q local=%v clean=%q\n", path, filepath.IsLocal(path), filepath.Clean(path))
	}
}

这段示例的重点是比较两个结果：local=false 的输入不能直接拼到受保护目录上；local=true 只说明它通过了词法边界。路径是否存在、是否可读、是否指向符号链接，需要在后续访问阶段另外处理。

在 Join 之前建立一个拒绝入口

实际项目里不要让调用方先 Join 再想办法补救。把判断封装在接收用户输入的函数里，成功时只返回拼好的路径，失败时返回明确错误，调用者就不容易遗漏这一层。

package safejoin

import (
	"fmt"
	"path/filepath"
)

// JoinLocal 只接受能留在 base 子树中的词法相对路径。
func JoinLocal(base, userPath string) (string, error) {
	if !filepath.IsLocal(userPath) {
		// 先拒绝绝对路径、空路径和父目录穿越，再进行拼接。
		return "", fmt.Errorf("path is not local: %q", userPath)
	}

	// IsLocal 已保证 userPath 不会把 Join 的结果带到 base 之外。
	return filepath.Join(base, userPath), nil
}

调用方拿到错误后可以返回 400、跳过压缩包条目或记录一次输入拒绝。不要为了“让路径可用”而把 ../ 删除、把绝对路径改成相对路径，或者先 Clean 再放行；那会把输入意图改写成另一个路径。

三个容易误判的边界

Clean 不是安全检查

Clean 是纯词法清理函数。它可以让路径字符串更短、更规范，但不等于“这个输入原本就在 base 子树内”。安全入口应先用 IsLocal 做接受或拒绝，再按业务需要清理或拼接。

IsLocal 不解析符号链接

官方文档明确说明 IsLocal 不考虑文件系统中的符号链接。一个词法上本地的目录名，仍可能通过符号链接指向其他位置。如果程序面对的是不可信目录或多租户文件空间，就需要使用更严格的目录句柄、Root 访问策略或部署层隔离，不能只凭这个布尔值放行。

IsLocal 不判断存在性和权限

路径通过后，打开文件仍可能得到不存在、权限不足或类型不匹配等错误。把这些错误留给 os.Open、os.OpenFile 等实际访问函数处理，并在边界处区分“输入不接受”和“资源访问失败”。

把判断结果整理成决策表

最后确认实现是否符合边界

如果需求只是“用户只能提交当前目录下的相对文件名”，filepath.IsLocal 配合 filepath.Join 就是清晰的第一道门。实现时记住四点：

• 判断对象是原始用户输入，不是被 Clean 改写后的字符串。
• 只有返回 true 才进入 Join(base, userPath)。
• 把路径拒绝、文件不存在和权限错误分成不同错误语义。
• 遇到符号链接、共享目录或强隔离需求时，增加文件系统级控制。

相关问题

filepath.IsLocal 能防止符号链接逃逸吗？

不能。它只做词法分析，不读取文件系统，也不追踪符号链接。需要额外的访问隔离策略。

为什么不直接判断 filepath.IsAbs？

只判断绝对路径仍会放过 ../secret.txt 这类父目录路径，也无法覆盖空输入和 Windows 保留名。IsLocal 的语义更贴近“留在当前子树内的相对路径”。

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

不代表。它不访问文件系统，存在性、类型和权限要由实际打开操作判断。