登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  Golang >  Go教程

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 与 Go archive/zip 预压缩载荷契约关系说明图
图1:FileHeader、预压缩载荷和 CreateRaw 的静态关系说明图,不是截图或运行证据。

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 返回写入接口与 Writer.Close 归档边界关系说明图
图2:CreateRaw、预压缩载荷和 Writer.Close 的静态边界说明图,不是终端截图或运行结果。

这里还有一个常被忽略的边界:如果条目写入中途失败,仍然应该让上层决定是否丢弃整个归档文件;不要把“已经写入了一部分条目”误认为文件可安全交付。

什么时候不该使用 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 就不会停留在“能写进去但无法可靠解压”的状态。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>