Go archive/zip.Writer.AddFS 怎样把目录写入 ZIP

如果输入已经是一个 fs.FS，把整棵目录树写进 ZIP 不需要自己递归目录。archive/zip 的 Writer.AddFS 会从文件系统根目录遍历文件，按原有目录结构创建 ZIP 条目；写完后仍必须调用 Close，因为中央目录要在收尾阶段写入。

官方地址：https://pkg.go.dev/archive/zip#Writer.AddFS

为什么 AddFS 适合整棵目录树

手动生成 ZIP 时，通常要完成遍历目录、拼接相对条目名、打开文件、复制内容、关闭文件和处理目录项。只要输入能表示为 fs.FS，这些动作就可以交给 Writer.AddFS 组合完成。官方文档把它定义为从 FS 根目录开始遍历，并使用 deflate 写入，同时保持目录结构；该方法从 Go 1.22.0 起提供。

这里的“根目录”是 FS 视角的根，不一定是操作系统的根目录。例如 os.DirFS("./release") 暴露的是 release 目录内部，ZIP 条目会从它的相对路径开始，而不是把 ./release 这个磁盘前缀写进去。

用 os.DirFS 把目录写入 ZIP

下面的例子把 ./release 目录映射成 fs.FS，再交给 AddFS。代码中的 defer 只负责关闭本地输出文件；ZIP Writer 的 Close 必须在 AddFS 成功后显式检查。

package main

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

func archiveDir(sourceDir, zipName string) error {
    // os.Create 负责创建 ZIP 容器文件，失败时不进入后续写入。
    out, err := os.Create(zipName)
    if err != nil {
        return fmt.Errorf("create zip %q: %w", zipName, err)
    }
    defer func() {
        // 这里释放操作系统文件描述符；归档收尾由 zw.Close 完成。
        _ = out.Close()
    }()

    // DirFS 把 sourceDir 作为 FS 根，避免把机器上的绝对前缀写入条目名。
    sourceFS := os.DirFS(sourceDir)
    zw := zip.NewWriter(out)

    // AddFS 遍历整棵目录树并保留相对目录结构。
    if err := zw.AddFS(sourceFS); err != nil {
        return fmt.Errorf("add directory to zip: %w", err)
    }

    // Close 写入 ZIP 中央目录，必须检查它的结果。
    if err := zw.Close(); err != nil {
        return fmt.Errorf("finish zip: %w", err)
    }
    return nil
}

func main() {
    // 示例调用：./release 下的内容进入 release.zip。
    if err := archiveDir("./release", "release.zip"); err != nil {
        fmt.Println(err)
    }
}

如果 release 下有 bin/app 和 config/app.toml，ZIP 中对应的条目就是 bin/app 与 config/app.toml。sourceDir 这个外层目录名不会自动成为前缀。这样生成的包更适合被另一段 Go 代码用 zip.Reader.Open 按相对路径读取。

AddFS 与 Close 的错误边界

不要只检查 os.Create。AddFS 可能在遍历目录、打开某个文件或写入条目时返回错误；即便所有条目都已写入，Close 仍可能在写中央目录时失败。生产代码至少要把这两个错误保留下来，日志中同时带上阶段名。

什么时候不能直接用 AddFS

AddFS 的优势是少写遍历代码，但它不是所有归档需求的终点。下面几类需求通常需要自己遍历：

• 过滤文件：只打包 .json 或排除临时目录时，要在遍历阶段决定哪些条目进入 ZIP。
• 改名或加前缀：需要把 bin/app 改成 release/bin/app 时，必须自己计算条目名。
• 自定义元数据：需要设置权限、修改时间或额外头字段时，使用 zip.FileInfoHeader 和 CreateHeader 更直接。
• 混合来源：一部分文件来自 embed.FS，另一部分来自磁盘时，可以先统一成遍历逻辑，再按条目写入。

手动实现时仍应遵守同一个边界：ZIP 条目使用相对、正斜杠分隔的路径；不要把用户输入未经限制地拼成条目名。是否允许符号链接、是否跟随链接，也应在输入 FS 的设计中明确，而不是交给条目字符串猜测。

常见问题

AddFS 会把 sourceDir 这个目录名写进 ZIP 吗？

不会。使用 os.DirFS(sourceDir) 后，sourceDir 是 FS 的根，条目从其内部的相对路径开始。若想保留外层目录名，应在手动遍历时显式增加前缀。

为什么 AddFS 成功了还必须 Close？

ZIP 的中央目录在归档末尾写入。AddFS 完成条目写入不等于底层 ZIP 已完整封口，必须调用并检查 Close。

能不能用 AddFS 排除某个目录？

直接调用不能传过滤函数。需要过滤时改用 fs.WalkDir，跳过目标目录后再调用 Create 或 CreateHeader 写入。