Go archive/zip 写入目录条目时怎么避免路径混乱

用 Go 的 archive/zip 打包目录时，最容易出错的不是压缩算法，而是“条目名”怎么写。ZIP 内部路径应使用相对路径和正斜杠；目录条目还要以 / 结尾。把 C:\\work\\report.txt 或用户传入的 ../secret.txt 直接交给 Writer，跨平台读取和安全边界都会变得不清楚。

稳妥的做法是先把输入路径转换成 ZIP 规则，再分别创建带尾斜杠的目录条目和普通文件条目；每个条目写完后再创建下一个，最后检查 Writer.Close。

先把 ZIP 内部路径和操作系统路径分开

操作系统路径可能使用反斜杠，ZIP 条目名则要求使用正斜杠，并且不能以盘符或根斜杠开头。建议把清理动作集中在一个函数里：先用 filepath.ToSlash 统一分隔符，再用 path.Clean 清理重复分隔符和当前目录段，最后拒绝空路径、绝对路径和包含 .. 的路径。

path.Clean 只是整理字符串，不等于完整的业务安全策略。这里额外拒绝父目录段，是为了让归档中的名称始终落在预期根目录下。

用一个规范化函数统一目录和文件条目

目录和文件都先经过同一个函数，区别只放在创建条目时。目录名称没有文件数据，尾斜杠是它的结构标志；文件名称不能因为“看起来像目录”就随意补斜杠。

package main

import (
    "archive/zip"
    "errors"
    "path"
    "path/filepath"
    "strings"
)

func normalizeZipName(raw string) (string, error) {
    // ZIP 内部统一使用正斜杠，不能把宿主机分隔符带进归档。
    name := path.Clean(filepath.ToSlash(strings.TrimSpace(raw)))
    if name == "." || name == "" || strings.HasPrefix(name, "/") {
        return "", errors.New("ZIP 条目必须是非空相对路径")
    }
    // 拒绝父目录段，避免归档名脱离预期目录边界。
    for _, part := range strings.Split(name, "/") {
        if part == ".." {
            return "", errors.New("ZIP 条目不能包含父目录段")
        }
    }
    return name, nil
}

func addDirectory(w *zip.Writer, raw string) error {
    name, err := normalizeZipName(raw)
    if err != nil {
        return err
    }
    if !strings.HasSuffix(name, "/") {
        name += "/"
    }
    // 目录条目只记录结构，不写入文件内容。
    _, err = w.Create(name)
    return err
}

func addFile(w *zip.Writer, raw string, data []byte) error {
    name, err := normalizeZipName(raw)
    if err != nil {
        return err
    }
    header := &zip.FileHeader{Name: name, Method: zip.Deflate}
    // CreateHeader 返回当前文件条目的写入器。
    dst, err := w.CreateHeader(header)
    if err != nil {
        return err
    }
    // 当前条目写完前，不要创建下一个条目。
    _, err = dst.Write(data)
    return err
}

目录条目、文件条目和 Close 各自负责什么

zip.NewWriter 只负责把条目写到目标 io.Writer。Create 适合快速创建文件或目录，CreateHeader 适合需要显式指定 Name、压缩方法等元数据的文件。调用后，Writer 会接管传入的 FileHeader，不要再修改它。

还有两个常见误区：第一，重复名称不会覆盖旧条目，而是继续追加；第二，Close 不会关闭底层文件，但会补写 ZIP 的 central directory，因此它的错误不能用 defer w.Close() 静默丢掉。

写一个完整的打包收尾

实际项目可以把多个文件描述为列表，依次写入一个 bytes.Buffer 或打开的输出文件。下面的收尾重点是：先判断每次添加的错误，再单独判断 Close。

func buildArchive() ([]byte, error) {
    var out bytes.Buffer
    w := zip.NewWriter(&out)

    if err := addDirectory(w, "docs"); err != nil {
        return nil, err
    }
    if err := addFile(w, "docs/readme.txt", []byte("目录条目已固定\n")); err != nil {
        return nil, err
    }
    if err := addFile(w, "docs/config/app.json", []byte("{}\n")); err != nil {
        return nil, err
    }
    // Close 会写 central directory，必须检查它的返回值。
    if err := w.Close(); err != nil {
        return nil, err
    }
    return out.Bytes(), nil
}

这个片段还需要在文件顶部引入 bytes。输出清单应类似 docs/、docs/readme.txt 和 docs/config/app.json。如果只创建文件条目而没有显式创建 docs/，很多读取器仍能根据文件名推断目录，但需要目录本身作为条目时就应保留尾斜杠。

发布前用条目清单验收

如果 ZIP 来自用户输入，还应把“原始名称”和“归一化名称”分开记录，遇到同名文件时明确选择拒绝、改名还是覆盖策略。archive/zip 的 Writer 不替你做业务层去重，越早决定规则，后面越容易排查。

常见问题

为什么目录名必须补一个斜杠？

ZIP 用尾斜杠表达目录条目，目录本身不承载文件数据。没有尾斜杠时，它更像一个普通文件名。

能不能直接使用 filepath.Join？

可以用它处理宿主机路径，但交给 ZIP Writer 前仍应调用 filepath.ToSlash，确保归档内部统一使用正斜杠。

重复条目会覆盖旧文件吗？

不会。官方文档说明重复名称会追加到 ZIP 中，所以应在业务层维护已写入名称集合。

为什么必须检查 Close 的错误？

因为 Close 会写入 central directory；前面的内容写成功，不代表归档尾部一定成功。

收尾检查

把 ZIP 路径当成独立命名空间处理：正斜杠、相对路径、目录尾斜杠和显式去重先确定，再调用 Writer。最后同时核对条目清单与 Close 错误，目录结构才不会在换平台或换读取器后发生意外变化。