Go archive/zip写入 Zip 时处理重复条目的实现方法

用 Go 的 archive/zip 生成压缩包时，重复文件名不会自动覆盖旧内容。Writer.Create 会把同名条目继续追加，因此真正可靠的做法是在调用它之前先统一 Zip 内路径，再用 map 记录已经接收的名称：需要严格归档就直接报错，需要“最后一份生效”就先收集数据，最后每个名称只写一次。

为什么 Create 不会覆盖同名 Zip 条目

官方文档对 Writer.Create 的定义很明确：重复名称不会覆盖之前的条目，而是追加到 Zip 文件中。也就是说，下面的两次调用代表两个目录记录，后一次不会回到前一次的位置修改内容。压缩包写入还是顺序操作，当前返回的 writer 必须写完，才能进入下一次 Create 或关闭 writer。

这会带来两个常见误判：一是把“同名”当成覆盖，二是只比较原始文件名。比如 docs\\readme.md、docs/readme.md 和带有多余 ./ 的路径，在业务上可能是同一个 Zip 位置。去重应发生在路径清理之后。

严格模式：写入前规范化并拒绝重复

如果 Zip 用于发布包、备份或交付物，重复输入通常意味着上游扫描结果不稳定，建议保留第一次出现的位置并返回错误，让调用方修复数据，而不是静默丢弃。下面的示例只演示内存字符串，接入文件时把 item.Body 换成 io.Copy 即可。

package main

import (
    "archive/zip"
    "fmt"
    "io"
    "path"
    "strings"
)

type Item struct {
    Name string
    Body string
}

func normalizeZipName(raw string) (string, error) {
    // Zip 统一使用正斜杠，先处理跨平台输入，再清理无效路径。
    name := strings.ReplaceAll(strings.TrimSpace(raw), "\\\\", "/")
    clean := path.Clean(name)
    if clean == "." || clean == ".." || strings.HasPrefix(clean, "/") || strings.HasPrefix(clean, "../") {
        return "", fmt.Errorf("invalid zip name %q", raw)
    }
    return clean, nil
}

func writeUniqueZip(dst io.Writer, items []Item) (err error) {
    zw := zip.NewWriter(dst)
    defer func() {
        // Close 会写入中央目录；即使前面出错，也要把 Close 错误纳入返回值。
        closeErr := zw.Close()
        if err == nil {
            err = closeErr
        }
    }()

    seen := make(map[string]struct{}, len(items))
    for _, item := range items {
        name, normalizeErr := normalizeZipName(item.Name)
        if normalizeErr != nil {
            return normalizeErr
        }
        if _, exists := seen[name]; exists {
            // 把重复名称暴露给上游，避免生成含歧义的归档。
            return fmt.Errorf("duplicate zip entry %q", name)
        }
        seen[name] = struct{}{}

        part, createErr := zw.Create(name)
        if createErr != nil {
            return createErr
        }
        // 当前条目写完后，循环才会进入下一次 Create。
        if _, writeErr := io.WriteString(part, item.Body); writeErr != nil {
            return writeErr
        }
    }
    return nil
}

这里的关键不是 seen 本身，而是它使用了规范化后的 name。这样可以把“输入形式不同但 Zip 位置相同”的情况归并到同一个键。生产代码还应给错误附带输入来源，便于定位是哪一条扫描记录产生了重复。

需要最后一份生效时先收集再写出

有些场景确实需要后来的内容替换前一份，例如多个生成阶段都产出同一个报告。此时不要连续调用 Create 再期待覆盖，而是把替换动作放在内存集合中，并保留一个独立顺序切片，避免直接遍历 map 造成输出顺序漂移。

latest := make(map[string]string)
order := make([]string, 0, len(items))
for _, item := range items {
    name, err := normalizeZipName(item.Name)
    if err != nil {
        return err
    }
    if _, firstSeen := latest[name]; !firstSeen {
        // 首次出现时记录顺序，后续只替换内容。
        order = append(order, name)
    }
    latest[name] = item.Body
}

for _, name := range order {
    // 输出阶段每个逻辑路径只创建一次，覆盖已在 map 中完成。
    part, err := zw.Create(name)
    if err != nil {
        return err
    }
    if _, err = io.WriteString(part, latest[name]); err != nil {
        return err
    }
}

发布前的 Zip 重复条目检查清单

先确认重复策略，再确认实现细节。路径中不要混用反斜杠和正斜杠，也不要把绝对路径或 ../ 路径直接交给 writer。每次 Create 后都要完成当前条目的写入；最后必须检查 zw.Close()，因为中央目录是在关闭时写入的。若还要读取结果，优先遍历 Reader.File 查看实际条目名称，不要把“能打开 Zip”误认为“条目一定唯一”。

常见问题

重复调用 Create 会返回错误吗？

不会因为名称重复自动报错。重复名称会继续追加，所以是否拒绝要由业务层的 map 或其他索引决定。

能不能删除 Zip 里前面已经写入的条目？

archive/zip.Writer 是顺序写出模型，不提供回到已写条目原地删除或覆盖的操作。需要替换时应重新组织待写集合并重新生成归档。

为什么不能直接遍历 map 写 Zip？

map 的遍历顺序不应作为业务顺序。若下游需要稳定归档，像示例一样单独保存首次出现的名称顺序，再按顺序写出。