Go archive/zip.Writer.CreateRaw 怎样写入预压缩 ZIP 条目
来源:17golang原创
时间:2026-11-17 03:45:13 171浏览 收藏
Go archive/zip.Writer.CreateRaw 怎样写入预压缩 ZIP 条目
我第一次看到 archive/zip.Writer.CreateRaw 时,最容易犯的错是把它当成“另一个压缩入口”。其实它的定位正好相反:数据已经按照 ZIP 条目声明的压缩方法准备好了,CreateRaw 只负责把这段预压缩载荷放进归档,并把对应的条目元数据写进去。
因此,正确思路是先准备与载荷一致的 zip.FileHeader,再调用 CreateRaw 获取一个 io.Writer,最后写入预压缩字节并关闭整个 zip.Writer。如果手里只有未压缩原文,就应该使用 Create 或先自行完成压缩,不能把原文直接交给 CreateRaw。
官方文档:https://pkg.go.dev/archive/zip#Writer.CreateRaw
CreateRaw的关键不是“少调用一次压缩函数”,而是让FileHeader里的 Method、压缩后大小、原始大小和 CRC-32 与将要写入的字节完全对应。
先区分 Create 和 CreateRaw
Writer.Create 接受文件名,返回写入接口,调用方写入的是未压缩数据,ZIP writer 会根据默认方法处理压缩。Writer.CreateRaw 接受一个已经准备好的 *zip.FileHeader,调用方写入的是该条目的原始压缩数据。
| 入口 | 写入内容 | 元数据责任 |
|---|---|---|
Create | 未压缩原文 | 由 ZIP writer 组织条目压缩信息 |
CreateRaw | 已压缩载荷 | 调用方准备 FileHeader 并与载荷保持一致 |

FileHeader 与预压缩数据必须对得上
使用 CreateRaw 时,至少要把条目名、压缩方法、压缩后长度、未压缩长度和 CRC-32 当作一组契约来看。CompressedSize64 描述你准备写入的压缩载荷长度,UncompressedSize64 描述解压后的原始长度,CRC32 则对应原始数据的校验值。
这里有一个很实用的判断:如果压缩载荷来自别的压缩器,就要使用它产出的实际方法和元数据;不要只复制文件名,然后猜一个大小或 CRC-32。ZIP 中央目录依赖这些字段,字段和载荷不一致时,问题往往会在其他工具解压或校验时才暴露。
package main
import (
"archive/zip"
"hash/crc32"
)
func makeRawHeader(name string, original, compressed []byte) *zip.FileHeader {
// FileHeader 的尺寸字段必须描述将要写入的原始数据和压缩载荷。
header := &zip.FileHeader{
Name: name,
Method: zip.Store,
UncompressedSize64: uint64(len(original)),
CompressedSize64: uint64(len(compressed)),
CRC32: crc32.ChecksumIEEE(original),
}
return header
}
上面的示例用 zip.Store 展示契约关系:它不压缩原文,因此 compressed 应该就是要写入的原始字节。若使用 Deflate 等压缩方法,compressed 必须是相应方法已经产出的载荷,三个尺寸/校验字段仍然要按真实数据填写。
调用 CreateRaw 并写入预压缩载荷
拿到 header 后,调用 CreateRaw。它返回的写入接口只是“当前 ZIP 条目的入口”,不是新的压缩器。调用方需要把预压缩载荷完整写入,并处理短写或底层写入错误。
package main
import (
"archive/zip"
"fmt"
"io"
)
func addRawEntry(zw *zip.Writer, header *zip.FileHeader, compressed []byte) error {
// CreateRaw 不会替你重新压缩;header 必须与 compressed 的格式和长度匹配。
entry, err := zw.CreateRaw(header)
if err != nil {
return fmt.Errorf("创建 ZIP 原始条目失败: %w", err)
}
// WriteString 也可以写字节,但 io.Copy 更适合接入已有流;这里用 Write 展示短写检查。
written, err := entry.Write(compressed)
if err != nil {
return fmt.Errorf("写入预压缩载荷失败: %w", err)
}
if written != len(compressed) {
return fmt.Errorf("预压缩载荷写入不完整: %d/%d", written, len(compressed))
}
return nil
}
func copyRawEntry(zw *zip.Writer, header *zip.FileHeader, src io.Reader) error {
// 当预压缩数据来自文件或网络流时,保持流式复制,不把整段载荷再次压缩。
entry, err := zw.CreateRaw(header)
if err != nil {
return fmt.Errorf("创建 ZIP 原始条目失败: %w", err)
}
if _, err := io.Copy(entry, src); err != nil {
return fmt.Errorf("复制预压缩载荷失败: %w", err)
}
return nil
}
如果来源是 io.Reader,还要提前知道或可靠地得到压缩后长度、原始长度和 CRC-32;否则就很难构造准确的 FileHeader。这也是 CreateRaw 更适合“已经完成压缩并带有元数据”的流水线,而不是临时压缩一段未知长度文本的原因。
Writer.Close 才是归档完成的边界
写完条目并不代表 ZIP 文件已经完整。zip.Writer.Close 会写出中央目录等归档收尾信息,调用方必须检查它的错误。工程代码里我会把文件关闭放在 writer 关闭之后:先让 ZIP writer 完成归档,再让底层文件落盘并关闭。
package main
import (
"archive/zip"
"fmt"
"os"
)
func buildArchive(path string, header *zip.FileHeader, compressed []byte) error {
// 创建底层文件后,后续所有错误都要带上资源清理责任。
file, err := os.Create(path)
if err != nil {
return fmt.Errorf("创建 ZIP 文件失败: %w", err)
}
defer file.Close()
zw := zip.NewWriter(file)
if err := addRawEntry(zw, header, compressed); err != nil {
return err
}
// Close 会写中央目录;不检查这个错误,可能得到一个尾部不完整的 ZIP。
if err := zw.Close(); err != nil {
return fmt.Errorf("完成 ZIP 归档失败: %w", err)
}
return nil
}

这里还有一个常被忽略的边界:如果条目写入中途失败,仍然应该让上层决定是否丢弃整个归档文件;不要把“已经写入了一部分条目”误认为文件可安全交付。
什么时候不该使用 CreateRaw
如果你的输入是普通文本、图片或业务对象的未压缩字节,通常直接调用 Create 更清楚。它让 archive/zip 负责压缩和条目元数据,减少手工同步大小与 CRC-32 的机会。
CreateRaw 更适合这些场景:压缩数据已经由上游统一生成;你需要把现成的压缩成员重新封装到 ZIP;或者流水线已经维护了压缩方法、尺寸和校验信息。它不适合用来绕过对数据格式的理解,也不能把任意压缩格式伪装成 ZIP 条目的 Method。
| 输入情况 | 建议 | 原因 |
|---|---|---|
| 只有未压缩原文 | 优先 Create | 由 ZIP writer 组织压缩和元数据 |
| 已有符合 ZIP Method 的压缩载荷 | 可以 CreateRaw | 复用上游压缩结果,但需准确填写 FileHeader |
| 压缩格式与 ZIP Method 不匹配 | 不要 CreateRaw | 条目声明和载荷无法被正确解释 |
几个容易继续追问的问题
CreateRaw 会不会自动计算 CRC-32?
不要把它当成自动校验入口。使用 CreateRaw 时应由调用方准备与原始数据对应的 CRC-32、原始大小和压缩后大小,并保证写入载荷确实符合声明的方法。
为什么写入成功了,解压工具仍然报错?
优先检查 Method、CompressedSize64、UncompressedSize64、CRC32 与实际载荷是否一致,再确认最终调用了 Writer.Close。CreateRaw 返回 nil 只代表条目入口创建成功,不代表整个归档已经完成。
能不能把 CreateRaw 的返回值复用给下一个条目?
不能把同一个条目 writer 当作多个条目的公共写入器。一个条目写完后,应回到 zip.Writer 创建下一个条目;所有条目完成后再统一 Close。
记住一句话就够了:CreateRaw 复用的是“已经压缩好的载荷”,不是替你完成压缩。把 FileHeader 当成载荷契约来维护,再把 Writer.Close 当成归档完成边界,预压缩数据嵌入 ZIP 就不会停留在“能写进去但无法可靠解压”的状态。
-
499 收藏
-
403 收藏
-
315 收藏
-
337 收藏
-
347 收藏
-
373 收藏
-
383 收藏
-
495 收藏
-
295 收藏
-
396 收藏
-
153 收藏
-
479 收藏
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 立即学习 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 立即学习 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 立即学习 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 立即学习 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 立即学习 485次学习