Go archive/zip.Writer.SetOffset 怎样在已有数据后追加 ZIP 内容

如果 ZIP 数据不是从底层 writer 的第 0 个字节开始，而是要追加在一段已有前缀之后，关键做法只有一个：在任何 ZIP 条目写入前调用 Writer.SetOffset(前缀长度)。它告诉 archive/zip，归档内部偏移要以容器中的真实位置计算。

随后正常调用 Create 写文件，并检查 Close。Close 会写入 ZIP 末尾的中央目录；底层 writer 仍由调用方管理。本文用内存字节流演示前缀、ZIP 条目和重新读取之间的关系。

SetOffset 修正的是 ZIP 数据起点

普通 ZIP 从 writer 的偏移 0 开始，条目头和中央目录中的偏移可以直接按归档自身位置计算。加入前缀后，ZIP 的第一个字节位于底层容器的第 n 个字节，中央目录也必须知道这个 n。

SetOffset 的参数就是 ZIP 数据在底层 writer 中的起点。它不负责写入前缀，也不会移动 writer 的当前位置；前缀应该由调用方先写入或以其他方式准备好。

先写前缀，再设置偏移

下面的示例把一段固定前缀写入 bytes.Buffer，再创建 ZIP Writer。此时 buf.Len() 就是 ZIP 数据的起点，传给 SetOffset 后再创建条目。

package main

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

func buildContainer() ([]byte, error) {
	var buf bytes.Buffer
	prefix := []byte("APP-PREFIX-v1\\x00")

	// 先写入容器自己的前缀，ZIP 数据随后从这个偏移开始。
	if _, err := buf.Write(prefix); err != nil {
		return nil, fmt.Errorf("写入前缀失败: %w", err)
	}

	zw := zip.NewWriter(&buf)
	// SetOffset 必须早于任何 ZIP 条目写入，参数是前缀在容器中的长度。
	zw.SetOffset(int64(len(prefix)))

	entry, err := zw.Create("meta/config.txt")
	if err != nil {
		return nil, fmt.Errorf("创建 ZIP 条目失败: %w", err)
	}
	// 条目内容写入完成后，才能继续创建条目或关闭 Writer。
	if _, err := io.WriteString(entry, "mode=embedded\\n"); err != nil {
		return nil, fmt.Errorf("写入条目失败: %w", err)
	}

	// Close 会写中央目录；它不会替调用方关闭 buf 对应的底层 writer。
	if err := zw.Close(); err != nil {
		return nil, fmt.Errorf("关闭 ZIP Writer 失败: %w", err)
	}
	return buf.Bytes(), nil
}

func main() {
	container, err := buildContainer()
	if err != nil {
		panic(err)
	}
	fmt.Printf("容器总长度: %d\\n", len(container))
}

这里有两个容易混淆的长度：len(prefix) 是 ZIP 起点，len(container) 是最终容器长度。后者包含前缀、条目数据、中央目录和结束记录，不能拿来传给 SetOffset。

为什么必须检查 Close

创建条目时，Writer 会先写入条目局部头和内容；中央目录要等所有条目完成后才能写出。因此只检查 Create 或条目内容写入，不足以判断最终 ZIP 是否完整。

实际项目中，Close 可能因为底层 writer 写失败而返回错误。若底层对象同时实现了 io.Closer，还要根据资源所有权单独关闭它；zip.Writer.Close 本身只负责结束 ZIP 写入。

从完整容器中重新读取 ZIP

写入后的容器包含前缀，因此读取时应把完整字节流交给实现了 io.ReaderAt 的对象，并传入完整大小。zip.NewReader 会在末尾定位中央目录，再依据其中的偏移读取条目。

func readContainer(container []byte) (string, error) {
	// ReaderAt 必须覆盖前缀和 ZIP 全部字节，不能只截取 ZIP 尾部。
	r, err := zip.NewReader(bytes.NewReader(container), int64(len(container)))
	if err != nil {
		return "", fmt.Errorf("打开嵌入 ZIP 失败: %w", err)
	}
	if len(r.File) == 0 {
		return "", fmt.Errorf("ZIP 中没有文件条目")
	}

	file := r.File[0]
	reader, err := file.Open()
	if err != nil {
		return "", fmt.Errorf("打开条目 %q 失败: %w", file.Name, err)
	}
	defer reader.Close()

	data, err := io.ReadAll(reader)
	if err != nil {
		return "", fmt.Errorf("读取条目 %q 失败: %w", file.Name, err)
	}
	return string(data), nil
}

读取函数只关心完整容器，不需要手动跳过前缀。真正决定条目位置的是写入阶段的 SetOffset；如果偏移错了，中央目录中的条目位置就可能指向错误的字节。

调用顺序和边界清单

小结

SetOffset 适合“已有数据 + ZIP”这种容器布局。前缀由调用方写入，偏移用前缀长度表示，设置必须早于 ZIP 数据写入，最终用 Close 完成中央目录。重新读取时保留完整字节流，就能让 zip.NewReader 按归档记录找到条目。

相关问题

• SetOffset 会自动写入前缀吗？不会，它只记录 ZIP 数据在底层 writer 中的起点。
• 可以在 Create 之后再调用 SetOffset 吗？不应这样做，官方约定是在 Writer 写入任何数据前调用。
• 为什么只调用 Flush 不够？Flush 主要刷新缓冲，中央目录的完整收尾应由 Close 负责。
• 读取嵌入 ZIP 是否要先手动切掉前缀？通常不需要；对完整容器使用 NewReader，并确保写入时偏移正确。