Go archive/zip 如何控制文件名

用 Go 生成 ZIP 时，归档里的文件名不是由本地文件名自动“猜出来”的，而是由 archive/zip 的入口参数决定：简单场景用 Writer.Create(name)，需要目录层级、压缩方式或元数据时用 FileHeader.Name 配合 Writer.CreateHeader。把名字先整理成相对路径，再写入内容，最容易得到稳定的归档结构。

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

archive/zip 的文件名由哪个入口决定

Writer.Create 适合直接给出一个归档内名称，例如 docs/readme.txt。它返回一个写入器，当前条目的内容必须写完，才能创建下一个条目。需要设置压缩方法、文件模式或修改时间时，应改用 FileHeader：

这里有一个容易忽略的所有权规则：调用 CreateHeader 后，Writer 可以修改传入的 header，调用方不要再复用或修改它。每次创建条目后先写完内容，也能避免下一个条目开始时前一个条目仍处于未完成状态。

用 FileHeader.Name 生成固定的归档路径

下面的示例把本地来源和归档内名称分开。业务真正需要控制的是 archiveName，它不会因为部署到另一台机器而改变：

package main

import (
    "archive/zip"
    "os"
    "path"
)

func main() {
    out, err := os.Create("release.zip")
    if err != nil {
        panic(err) // 创建目标归档失败时立即终止，避免继续写入无效句柄
    }
    defer out.Close() // 释放目标文件；真正的 ZIP 收尾由 zw.Close 完成

    zw := zip.NewWriter(out)
    defer zw.Close() // 写完所有条目后写入 ZIP 中央目录

    entries := []struct {
        archiveName string
        body        string
    }{
        {path.Join("reports", "2026", "summary.csv"), "name,total\\nalpha,3\\n"},
        {"assets/logo.svg", ""},
    }

    for _, item := range entries {
        header := &zip.FileHeader{Name: item.archiveName}
        header.Method = zip.Deflate // 明确使用 Deflate；不设置时默认是 Store
        w, err := zw.CreateHeader(header)
        if err != nil {
            panic(err) // 名称不符合 ZIP 相对路径规则时在这里暴露
        }
        if _, err = w.Write([]byte(item.body)); err != nil {
            panic(err) // 当前条目写入失败就不要继续生成后续条目
        }
    }
}

这个示例只展示结构，文章配图也是对应关系的说明图，不代表本机已经执行过命令。生成结果应当包含 reports/2026/summary.csv 和 assets/logo.svg 两个条目。生产代码中建议显式检查 zw.Close() 的错误，因为中央目录写入失败时，前面的条目看似写完，ZIP 仍可能不可用。

目录、重复名和中文名要先划清边界

文件名可控，不等于任意字符串都能安全写入 ZIP。写入前至少处理下面四种情况：

• 相对路径：不能以 / 开头，也不能带 Windows 盘符；统一使用 /，不要直接把 Windows 的反斜杠当成归档分隔符。
• 目录条目：如果要显式创建空目录，名称写成 reports/2026/，末尾斜杠表示目录且不应写文件内容。仅写文件条目时，多数解压器也会按路径推导父目录。
• 重复名称：Create 不会覆盖同名条目，而是把新条目继续追加。若业务要求唯一文件名，应在写入前用集合检查，而不是指望 ZIP 自动去重。
• 中文与非 UTF-8：有效 UTF-8 名称通常由库自动设置 ZIP 的 UTF-8 标志。不要为了“兼容旧软件”随意设置 NonUTF8，它可能让不同解压器按本地编码解释同一个名字。

另外，FileInfoHeader 会根据 fs.FileInfo.Name() 填入基础名。如果来源文件是 /data/export/report.csv，得到的默认名通常只是 report.csv；要放到 reports/2026/ 下，必须在调用 CreateHeader 前重新赋值 header.Name。

生成归档前的文件名检查清单

可以把检查集中在“准备条目”这一步，而不是写完 ZIP 再猜解压结果：

1. 确定展示给用户的归档路径，使用 path.Join 或统一的正斜杠规则。
2. 拒绝绝对路径、盘符路径和不允许的空名称；如需目录，明确补上末尾 /。
3. 用集合记录已经写入的名称；允许重名时也要在业务层记录它的出现顺序。
4. 需要复制本地属性时先调用 FileInfoHeader，然后覆盖 Name，再设置 Method 等元数据。
5. 全部条目写入后检查 zw.Close()，不要只检查单个 w.Write。

这样控制文件名，归档结构就由业务规则决定，而不是被本地目录、操作系统分隔符或解压器的容错行为牵着走。

常见问题

只调用 Create 能不能把文件放进子目录？

可以，直接传入 reports/summary.csv 即可。只有需要额外元数据或压缩方式时，才需要换成 CreateHeader。

同一个文件名再次 Create 会覆盖吗？

不会。它会追加新的 ZIP 条目，最终由解压器决定如何展示同名文件。需要唯一结果时，应在业务层改名或拒绝重复。

为什么 FileInfoHeader 后还要改 Name？

因为文件信息接口只提供基础名，而归档路径属于你的发布规则。复制属性后重新设置 header.Name，才能得到期望的目录层级。