Go archive/zip 处理文件名与目录条目

处理 ZIP 时，文件名不要从解压后的操作系统路径猜，而应直接读取 archive/zip 条目的 FileHeader.Name。遍历 Reader.File 可以拿到归档中的每个条目：名称以正斜杠分隔，通常以斜杠结尾的条目表示目录，其他条目才适合打开内容。

官方文档地址：https://pkg.go.dev/archive/zip

最小判断规则是：先用 zip.OpenReader 打开并关闭归档，再读取 f.Name；用 f.FileInfo().IsDir() 跳过目录，只有普通文件才调用 f.Open()。不要把 ZIP 条目名当成当前系统的原生路径。

• Reader.File 是 ZIP 条目集合，File.Name 来自嵌入的 FileHeader.Name。
• 目录条目以尾斜杠表达目录语义，目录本身通常没有要读取的文件内容。
• OpenReader 和条目返回的 ReadCloser 都要在合适的生命周期结束时关闭。

先看懂 ZIP 条目的 Name 和目录标记

ZIP 的条目名是归档内部的相对名称，官方 API 约定使用正斜杠，而不是 Windows 反斜杠。比如 docs/readme.txt 表示文件条目，docs/ 表示目录条目。这个名称是 ZIP 元数据的一部分，不等于解压到本机后的绝对路径。

用 Reader.File 遍历文件名和目录条目

只想列出清单时，不需要打开每个文件。把 f.Name 当作展示或索引键，并先用 FileInfo().IsDir() 判断类型，可以避免对目录调用内容读取接口。

package main

import (
	"fmt"
	"log"
	"archive/zip"
)

func main() {
	reader, err := zip.OpenReader("assets.zip")
	if err != nil {
		log.Fatal(err)
	}
	defer reader.Close() // 归档句柄在遍历完成后统一关闭。

	for _, file := range reader.File {
		if file.FileInfo().IsDir() {
			fmt.Printf("目录: %s\\n", file.Name) // 目录名通常以正斜杠结尾。
			continue
		}
		fmt.Printf("文件: %s\\n", file.Name) // Name 是 ZIP 内部名称，不是本机绝对路径。
	}
}

这里的重点是“遍历条目元数据”，不是解压。即使目录条目没有实际内容，它仍可能出现在 Reader.File 中，因此不能只用“有没有扩展名”判断文件类型。

只对文件条目打开内容，并保留路径安全判断

需要读取文件内容时，再对普通文件调用 Open，并关闭返回的 ReadCloser。打开归档时如果返回的错误包含 zip.ErrInsecurePath，要先决定业务是否接受非本地条目名；不要把它当成普通的“文件不存在”。

func readFirstFile(path string) ([]byte, error) {
	reader, err := zip.OpenReader(path)
	if err != nil {
		// ErrInsecurePath 表示条目名可能不是本地相对路径，需按策略处理。
		return nil, err
	}
	defer reader.Close() // 关闭底层 ZIP 文件，避免文件描述符泄漏。

	for _, file := range reader.File {
		if file.FileInfo().IsDir() {
			continue // 目录只有条目信息，不作为内容输入。
		}
		rc, err := file.Open()
		if err != nil {
			return nil, err
		}
		data, readErr := io.ReadAll(rc)
		closeErr := rc.Close() // 读取完成后立即关闭当前条目的解压流。
		if readErr != nil {
			return nil, readErr
		}
		if closeErr != nil {
			return nil, closeErr
		}
		return data, nil
	}
	return nil, fmt.Errorf("没有普通文件条目") // 空归档或只有目录时给出明确结果。
}

上面的示例需要额外导入 fmt、io 和 archive/zip。示例只读取第一个普通文件；生产代码应根据业务键匹配 file.Name，并限制允许的条目名和读取大小。

文件名、目录和路径安全的几个边界

如果最终要把条目写到本地目录，文件名检查和目标路径拼接仍然是业务责任；读取到 file.Name 并不等于可以无条件写入文件系统。对于只展示清单的场景，保留原始条目名即可，不必先做本地化转换。

Go archive/zip 文件名与目录条目常见问题

为什么 ZIP 里的目录名常常以斜杠结尾？

这是 ZIP 条目表达目录的约定。Go 的 FileHeader.Name 文档也说明，尾斜杠表示目录并且不应有文件数据；实际判断仍应优先使用 FileInfo().IsDir()。

可以直接把 file.Name 交给 filepath.Join 吗？

不能把它当成已经安全的本地路径。ZIP 名称使用正斜杠，可能包含不适合落盘的路径成分；在写入文件系统前应单独做本地路径和目录穿越策略。

只列出文件名需要调用 file.Open 吗？

不需要。列清单只读取条目元数据；只有需要内容时才打开条目流，这样资源更少，也能把名称处理和内容处理分开。

结语

处理 Go ZIP 文件名时，记住三层关系即可：Reader.File 提供条目集合，FileHeader.Name 提供归档内部名称，FileInfo().IsDir() 区分目录和普通文件。先按正斜杠名称做判断，再按需调用 Open 并关闭资源，最后把 ErrInsecurePath 纳入路径策略，代码就不会把目录、文件和本机路径混在一起。