Go archive/zip 解压时怎么防止文件路径越界

Go 用 archive/zip 解压用户上传的文件时，不能直接把 f.Name 交给 filepath.Join。成员名可能带有绝对路径、..，也可能用反斜杠伪装成 Windows 路径。正确做法是先把它当作不可信的相对路径校验，再写入一个受控目录；如果程序运行在 Go 1.24 及以上，还可以用 os.Root 把符号链接和目录逃逸一起限制住。

为什么 filepath.Join 不能单独承担安全检查

filepath.Join(dest, name) 会清理路径，但清理不等于授权。成员名为 ../../etc/app.conf 时，结果仍可能落到 dest 之外；用 strings.HasPrefix 比较绝对路径又会把同前缀的兄弟目录误认为安全。ZIP 规范中的路径使用正斜杠，而目标系统可能把反斜杠当分隔符，所以检查必须放在写文件之前，并考虑跨平台解释方式。

先把 ZIP 成员名收敛为本地相对路径

下面的写法以 Go 1.23 及以上为例。filepath.Localize 把 ZIP 使用的斜线路径转换成操作系统路径；转换失败，或 filepath.IsLocal 返回 false，就直接跳过该成员。打开归档时还要处理 zip.ErrInsecurePath，不要把库已经发现的路径风险忽略掉。

func localMemberPath(name string) (string, error) {
	// ZIP 成员名先按斜线路径转换，避免直接把外部字符串交给文件系统。
	local, err := filepath.Localize(name)
	if err != nil {
		return "", fmt.Errorf("非法 ZIP 路径 %q: %w", name, err)
	}
	// IsLocal 拒绝绝对路径、空路径、父目录跳转和 Windows 保留名。
	if !filepath.IsLocal(local) {
		return "", fmt.Errorf("ZIP 路径越界: %q", name)
	}
	return local, nil
}

如果项目还要兼容没有 filepath.Localize 的旧 Go 版本，至少要把反斜杠按分隔符处理，再检查 filepath.IsLocal；不要只在 Linux 上测试，因为同一个归档可能在 Windows 上被重新解压。

写入时再加一道目标目录边界

通过路径检查后，目录条目只创建目录，普通文件才打开输出文件；符号链接条目建议直接拒绝。解压目标最好是新建的临时目录，避免目标目录中原有的符号链接被跟随。普通兼容写法如下：

func extractFile(dest string, f *zip.File) error {
	rel, err := localMemberPath(f.Name)
	if err != nil {
		return err
	}
	if f.FileInfo().IsDir() {
		// 目录权限只给解压任务需要的范围，避免继承过宽权限。
		return os.MkdirAll(filepath.Join(dest, rel), 0o750)
	}
	if f.Mode()&os.ModeSymlink != 0 {
		return fmt.Errorf("拒绝 ZIP 符号链接: %q", f.Name)
	}

	target := filepath.Join(dest, rel)
	if err := os.MkdirAll(filepath.Dir(target), 0o750); err != nil {
		return err
	}
	in, err := f.Open()
	if err != nil {
		return err
	}
	defer in.Close() // 每个成员单独关闭读取器，避免大量文件句柄堆积。
	out, err := os.OpenFile(target, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o640)
	if err != nil {
		return err
	}
	if _, err = io.Copy(out, in); err != nil {
		out.Close()
		return err
	}
	return out.Close() // 关闭时才确认缓冲数据已落盘。
}

这里的 IsLocal 防的是词法路径越界，不能替代对文件系统竞态的防护。如果解压目录会被其他进程修改，或者归档来自完全不可信的上传者，Go 1.24 及以上可用 os.OpenRoot(dest) 得到 *os.Root，再用 root 的 OpenFile、Mkdir 等方法操作相对路径。os.Root 会把访问限制在根目录树内，根外符号链接也会报错。

解压前后的检查清单

还应限制单个文件和整个归档的解压大小，必要时用带上限的读取器包住 f.Open()。路径安全只保证“写到哪里”，不能防止压缩炸弹、磁盘耗尽或恶意的大量小文件。

常见问题

只检查 strings.Contains(name, "..") 可以吗？

不可以。它会误伤合法文件名，也漏掉绝对路径、反斜杠和规范化后的组合路径。应检查转换后的路径是否为本地相对路径。

zip.Reader 返回 ErrInsecurePath 后还能继续用吗？

技术上返回值可能仍可用，但解压不可信归档时应把它当作失败处理，除非业务明确允许这些名称并且后续有独立、严格的路径策略。

filepath.Clean 能防止路径穿越吗？

不能。Clean 只做词法归一化；它可以帮助你观察最终路径，却不会证明最终路径仍在目标目录中。