Go archive/zip.Writer 如何复制文件条目：CreateHeader、写入顺序与 CRC 校验

如果只是把一个文件塞进 ZIP，真正容易出错的地方不在 zip.NewWriter，而在文件信息、条目写入和归档收尾的先后顺序。稳妥的做法是先打开源文件，用 zip.FileInfoHeader 生成条目头，再通过 CreateHeader 拿到写入器，最后让 io.Copy 完成内容复制，并把 Writer.Close 的错误当成最终结果的一部分。

复制 ZIP 条目时，先准备可靠的 FileHeader，再写入完整内容；只有源文件复制成功且 zip.Writer.Close 也成功，生成的 ZIP 才值得交给下游。

先把一个文件映射成 ZIP 条目

下面的示例只做一件事：把 ./input/report.csv 复制为 ZIP 内的 reports/today.csv。输出目录提前创建，避免把文件系统权限问题误判成 ZIP API 问题。

package main

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

func copyFileToZip(srcPath, zipPath string) error {
	src, err := os.Open(srcPath)
	if err != nil {
		return fmt.Errorf("open source: %w", err)
	}
	defer src.Close()

	info, err := src.Stat()
	if err != nil {
		return fmt.Errorf("stat source: %w", err)
	}

	dst, err := os.Create(zipPath)
	if err != nil {
		return fmt.Errorf("create zip: %w", err)
	}
	zw := zip.NewWriter(dst)

	header, err := zip.FileInfoHeader(info)
	if err != nil {
		dst.Close()
		return fmt.Errorf("build header: %w", err)
	}
	header.Name = "reports/today.csv"
	header.Method = zip.Deflate

	w, err := zw.CreateHeader(header)
	if err != nil {
		zw.Close()
		dst.Close()
		return fmt.Errorf("create entry: %w", err)
	}
	if _, err = io.Copy(w, src); err != nil {
		zw.Close()
		dst.Close()
		return fmt.Errorf("copy entry: %w", err)
	}
	if err = zw.Close(); err != nil {
		dst.Close()
		return fmt.Errorf("close zip writer: %w", err)
	}
	if err = dst.Close(); err != nil {
		return fmt.Errorf("close zip file: %w", err)
	}
	return nil
}

这里的 FileInfoHeader 只是在准备条目元数据，不会读取文件内容。header.Name 决定 ZIP 内的逻辑路径，和本地源文件名可以不同；header.Method 则明确要求使用 Deflate。真正的数据流从 io.Copy 才开始。

为什么写入顺序不能提前关闭

CreateHeader 成功后，返回的 w 只对应当前条目。它不是一个可以长期悬挂的普通文件句柄：当前条目的内容没有复制完，就不应该调用 zw.Close 去结束整个 ZIP。

执行路径可以按四个节点核对：

1. os.Open 打开源文件，读取位置位于文件开头。
2. zip.FileInfoHeader 把 os.FileInfo 转成 FileHeader。
3. CreateHeader 创建 reports/today.csv 条目，io.Copy 将源内容写入条目。
4. Writer.Close 写入中央目录，随后才关闭底层 dst。

如果在 io.Copy 之前关闭 zw，后续写入会落到已经结束的归档流程上；如果只检查 io.Copy 而忽略 zw.Close，中央目录写失败时也可能把一个不可用的 ZIP 当成成功产物。

CRC 校验应该在哪里确认

调用方通常不需要自己计算 CRC32。写入器会在内容流经过时记录条目数据，关闭归档时完成必要的条目收尾。对调用方来说，最重要的验收点是 io.Copy 和 zw.Close 都返回 nil。

生成后可以重新打开 ZIP，让标准库读取条目并校验内容：

func verifyZip(zipPath string) error {
	r, err := zip.OpenReader(zipPath)
	if err != nil {
		return err
	}
	defer r.Close()
	for _, f := range r.File {
		if f.Name != "reports/today.csv" {
			continue
		}
		body, err := f.Open()
		if err != nil {
			return err
		}
		_, copyErr := io.Copy(io.Discard, body)
		closeErr := body.Close()
		if copyErr != nil {
			return copyErr
		}
		if closeErr != nil {
			return closeErr
		}
		return nil
	}
	return fmt.Errorf("entry not found")
}

读取条目时把内容读完，标准库才有机会发现压缩数据损坏或 CRC 不匹配。只检查 f.Name 或条目数量，不能代替内容读取。

几个很容易混淆的失败点

源文件变了，头信息却来自旧快照

如果先读取 FileInfo，之后又让另一个进程替换源文件，条目元数据和实际字节可能不再对应。对重要归档，应该在同一个受控流程里打开并复制；需要一致性时，还要在业务层约束源文件不要并发改写。

只返回 io.Copy 的错误

这会漏掉中央目录写入失败、底层磁盘写失败等收尾错误。示例中每个提前返回分支都尝试关闭已创建的资源，正式代码还可以把清理错误写入日志，但不要覆盖最先发生的主错误。

把 ZIP 内路径当成本地路径

header.Name 是归档内部名称，建议使用稳定的相对路径，例如 reports/today.csv。不要把用户传入的绝对路径直接写进条目名，也不要让条目名携带不必要的上级目录跳转。

常见问题

必须手动给 FileHeader 填 CRC32 吗？

常规的流式写入不需要调用方手动填 CRC32。通过 CreateHeader 获得写入器后写入内容，并检查 Writer.Close；重新读取条目时再用完整读取做验收。

为什么生成的 ZIP 文件大小在 Writer.Close 前不稳定？

因为中央目录属于 ZIP 的收尾结构，Writer.Close 才会把它写完。要上传或计算最终文件大小，应在关闭 ZIP 写入器和底层文件后再进行。

只压缩一个文件也需要 CreateHeader 吗？

如果只需要默认条目名，可以使用更简短的创建方法；当你要控制归档内路径、权限信息或压缩方式时，FileInfoHeader 加 CreateHeader 更容易核对，也更适合后续增加验收步骤。

收尾检查

把文件复制进 ZIP 的最小可靠链路是：打开源文件，生成并修正 FileHeader，调用 CreateHeader，完成 io.Copy，关闭 Writer，再关闭目标文件，最后按需重新读取条目。只要把这条链路当作一个整体，CRC 和中央目录相关的问题就不会被一个“复制成功”的局部结果掩盖。