Go filepath.Clean 怎样防止相对路径越界

如果程序把用户传来的相对路径直接拼到上传目录，../secret.txt 这类输入就可能把目标带到安全根目录之外。filepath.Clean 只能做词法归一化，真正判断是否越界，还要把规范化后的候选路径与安全根目录交给 filepath.Rel 比较。

可靠的组合是：先拒绝空值和绝对路径，再用 Join 构造候选路径，最后用 Rel(root, candidate) 判断结果是否以 .. 开头。仅比较字符串前缀，或只调用 Clean，都不足以完成根目录约束。

• Clean：消除 .、内部 .. 和重复分隔符，结果仍然只是一个字符串。
• Join：把安全根目录与相对输入组合成候选路径，并再次做清理。
• Rel：计算候选路径相对根目录的位置；结果以 .. 开头时，说明它已经在根目录外。

先理解 filepath.Clean 到底改变了什么

Clean 按词法处理路径：合并重复分隔符，去掉当前目录元素，消除能够配对的父目录元素；输入为空或归一化后为空时会得到 .。它不会打开文件、读取目录，也不会解析符号链接。

例如，下面的例子只观察字符串变化。代码中的注释说明了每组输入想表达的边界，输出也没有被当作文件系统已经存在的事实。

package main

import (
	"fmt"
	"path/filepath"
)

func main() {
	inputs := []string{
		"docs/../config/app.yaml", // 内部 .. 抵消前一个目录
		"./images//avatar.png",    // . 和重复分隔符会被归一化
		"../secret.txt",           // 开头的 .. 不能凭 Clean 自动变安全
		"",                        // 空输入会得到 .
	}

	for _, input := range inputs {
		fmt.Printf("%q -> %q\n", input, filepath.Clean(input)) // 只打印词法结果
	}
}

为什么只调用 Clean 仍然可能越界

因为以相对路径开头的 .. 会被保留下来。例如 filepath.Clean("../secret.txt") 仍然是 ../secret.txt。如果随后把它与 /srv/uploads 拼接，得到的候选路径就会落到上传目录的父级。

另一个常见误区是检查字符串前缀：/srv/uploads-other 也以 /srv/uploads 开头，但它并不属于该目录。路径安全要比较路径关系，不要把目录边界当成普通字符串边界。

把用户输入组合到安全根目录

先把安全根目录本身清理成稳定的路径，再检查输入。对这个文章范围来说，输入应该是相对文件名；绝对路径、空字符串和只包含父级跳转的输入，都应在业务层拒绝。

package main

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

var errInvalidRelativePath = errors.New("invalid relative path")

func candidatePath(root, userPath string) (string, error) {
	if userPath == "" || filepath.IsAbs(userPath) { // 先挡住空值和绝对路径
		return "", errInvalidRelativePath
	}

	root = filepath.Clean(root) // 根目录先归一化，便于后续比较
	candidate := filepath.Join(root, userPath) // Join 会按平台分隔符组合并清理
	return candidate, nil
}

func main() {
	path, err := candidatePath("/srv/uploads", "images/avatar.png")
	if err != nil {
		fmt.Println("拒绝:", err) // 输入不满足相对路径约束
		return
	}
	fmt.Println(path) // 这里只展示候选字符串，尚未访问文件系统
}

这里的 Join 不是安全判定。它只是构造候选路径，所以返回成功后仍然必须进入下一步的 Rel 比较。

用 filepath.Rel 判断候选路径是否仍在根目录内

Rel(root, candidate) 会返回从根目录走到候选路径所需的相对路径。如果结果是 images/avatar.png 或 avatar.png，候选路径仍在根目录下；如果结果以 .. 开头，就表示需要先走出根目录。

package main

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

var errOutsideRoot = errors.New("path escapes root")

func safePath(root, userPath string) (string, error) {
	if userPath == "" || filepath.IsAbs(userPath) { // 只接受非空相对路径
		return "", errInvalidRelativePath
	}

	root = filepath.Clean(root)
	candidate := filepath.Join(root, userPath) // 生成待判断的候选路径
	rel, err := filepath.Rel(root, candidate) // 计算候选路径相对根目录的位置
	if err != nil {
		return "", fmt.Errorf("计算相对路径: %w", err) // 平台路径无法比较时保留原因
	}
	if rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
		return "", errOutsideRoot // .. 或 ../ 开头表示已经越出根目录
	}
	return candidate, nil // 通过词法边界判断后再交给后续文件操作
}

func main() {
	for _, input := range []string{"images/avatar.png", "../secret.txt"} {
		path, err := safePath("/srv/uploads", input)
		fmt.Printf("%q => %q, err=%v\n", input, path, err) // 观察允许和拒绝两类结果
	}
}

这个判断方案的边界

第一，Clean、Join 和 Rel 都是在做路径字符串的词法处理；它们不会替你创建目录、确认文件存在或检查操作系统权限。通过判断后，仍然要让后续文件操作处理权限和 I/O 错误。

第二，本方案讨论的是相对路径的词法越界。符号链接可能把一个看似位于根目录下的路径引向别处；如果业务允许用户影响目录内容，就需要把符号链接策略、目录权限和文件打开方式一起设计，不能把本例当成全部防护。

第三，路径分隔符与卷名受目标操作系统影响。发布到 Windows、Linux 或 macOS 时，应让 filepath 按目标平台工作，不要手工写死 / 或用字符串替换模拟路径。

一张表记住职责分工

实际落地时，可以把这三个调用封装在一个小函数中：入口拒绝空值和绝对路径，Join 形成候选，Rel 负责根目录边界，后续代码再执行打开、读取或写入。

常见问题

Clean 会自动删除所有 .. 吗？

不会。它会消除能够与前面普通路径元素配对的内部 ..，但相对路径开头的父级跳转仍可能保留。

为什么不用 strings.HasPrefix 判断目录？

字符串前缀没有目录边界语义，容易把相邻目录名误判为同一根目录。应该比较 Rel 的路径结果。

Rel 返回 .. 就一定是错误吗？

如果业务约束是“必须留在 root 内”，结果为 .. 或以 .. 加分隔符开头就应拒绝；如果业务本来允许访问兄弟目录，则规则需要另行定义。

通过 Rel 后就可以放心写文件吗？

还不够。它解决的是词法根目录边界；权限、符号链接、竞态和文件系统错误仍要由后续设计处理。

参考资料：https://pkg.go.dev/path/filepath。页面中的 Clean、Join 和 Rel 文档分别说明了路径归一化、组合和相对关系计算的语义。