Go crc32.New 怎么增量计算大文件校验值

我第一次给备份包加 CRC-32 时，最顺手的写法是 os.ReadFile 再调用 crc32.ChecksumIEEE。小文件没问题，文件一大，整份内容同时驻留内存就显得很浪费。更合适的做法是用 crc32.New 创建一个可持续写入的 hash.Hash32，让文件数据分块进入同一个校验状态。

大文件的默认选择是 crc32.New(table) 配合 io.Copy：文件按流读取，内存只保留复制缓冲和 CRC 状态，最后调用 Sum32() 得到校验值。

官方地址：https://pkg.go.dev/hash/crc32

本文比较四种常见写法：Checksum、New + io.Copy、New + 手动读取 和 Update。重点不是背 API，而是根据数据是否已经在内存、是否需要进度回调、是否要与既有协议对齐来选。

为什么大文件更适合 crc32.New

crc32.Checksum 的参数是完整的 []byte。如果数据本来就在内存里，这个接口非常直接；但如果数据来自数 GB 的文件，为了凑出一个 []byte 先调用 os.ReadFile，内存占用就会跟文件大小一起增长。

crc32.New 返回 hash.Hash32。这个对象同时实现 io.Writer：每次写入一块字节，它都会在已有状态上继续计算。文件可以分成任意大小的块，块的边界不会改变最终 CRC，只要字节顺序和使用的多项式一致。

这个模型让我少操心两件事：不用自己管理 EOF，也不用把整个文件拼成一个切片。需要保留的是文件关闭错误边界、复制过程的读取错误，以及对端究竟使用哪张 CRC 表。

默认方案：crc32.New 配合 io.Copy

下面的函数以 CRC-32 IEEE 为例，同时返回校验值和实际读取的字节数。io.Copy 会持续复制到 EOF；正常读完时错误是 nil，文件读取途中失败才会返回错误。

package main

import (
    "fmt"
    "hash/crc32"
    "io"
    "os"
)

func fileCRC32(path string, table *crc32.Table) (uint32, int64, error) {
    file, err := os.Open(path)
    if err != nil {
        return 0, 0, err
    }
    defer file.Close() // 只读校验完成后释放文件描述符

    digest := crc32.New(table)
    size, err := io.Copy(digest, file) // 数据分块进入同一个 CRC 状态
    if err != nil {
        return 0, size, err
    }
    return digest.Sum32(), size, nil
}

func main() {
    sum, size, err := fileCRC32("archive.bin", crc32.IEEETable)
    if err != nil {
        fmt.Println("计算失败:", err)
        return
    }
    fmt.Printf("bytes=%d crc32=%08x\n", size, sum) // 固定输出 8 位十六进制
}

%08x 只是显示格式，不参与计算。CRC-32 是 32 位值，补足 8 个十六进制字符便于和清单、协议字段或其他工具的结果比较。比较之前还要确认字节序、大小写和是否包含前缀 0x 等文本约定。

对我来说，这个写法适合绝大多数“一次打开、顺序读完、得到一个 CRC”的任务。代码短，错误边界清楚，而且不需要人为选择读取块大小。

需要进度和复用缓冲区时手动读取

有些任务要展示进度、限速、统计每块耗时，或者把同一个缓冲区放进池中复用。这时手动循环更灵活。最容易忽略的细节是：Read 可能同时返回 n > 0 和一个非空错误，应该先处理已经读到的字节，再判断错误。

func fileCRC32WithProgress(
    file *os.File,
    table *crc32.Table,
    onProgress func(readBytes int64),
) (uint32, error) {
    digest := crc32.New(table)
    buf := make([]byte, 256*1024) // 可按业务负载调整并复用
    var total int64

    for {
        n, readErr := file.Read(buf)
        if n > 0 {
            _, _ = digest.Write(buf[:n]) // 标准库 Hash.Write 不返回错误
            total += int64(n)
            if onProgress != nil {
                onProgress(total)
            }
        }

        if readErr == io.EOF {
            break // 正常读完，保留本次已经写入的 n 个字节
        }
        if readErr != nil {
            return 0, readErr
        }
    }
    return digest.Sum32(), nil
}

手动循环的代价是代码更长，边界更多。若没有进度、节流或共享缓冲区需求，我通常仍选 io.Copy；若需要复用调用方提供的缓冲区，也可以使用 io.CopyBuffer，但应知道当源实现 WriterTo 或目标实现 ReaderFrom 时，提供的缓冲区可能不会被使用。

Checksum、New 和 Update 怎么选

这几个 API 算的都是 CRC-32，区别主要在输入形态和状态表达方式。把它们放到同一张图里，比只看函数名更容易作决定。

crc32.Update 也能增量计算：

table := crc32.MakeTable(crc32.Castagnoli)
var sum uint32

for _, chunk := range chunks {
    sum = crc32.Update(sum, table, chunk) // 在已有 CRC 数值上继续加入当前块
}
fmt.Printf("%08x\n", sum)

如果上游已经把数据拆成切片，而且系统只想保存一个 uint32 状态，Update 很直观；如果输入天然是 io.Reader，New 的 Writer 接口通常更容易接入现有 I/O 组合。

多项式不一致，比缓冲区大小更容易出错

CRC-32 不是一个唯一结果集合。标准库预定义了 IEEE、Castagnoli 和 Koopman 多项式，crc32.New 使用哪张 Table，结果就遵循哪种规则。IEEE 很常见；Castagnoli 用于包括 iSCSI 在内的场景，并有不同的错误检测特性。

如果已有系统写明使用 CRC-32C，通常对应 Castagnoli；如果写明 CRC-32 IEEE，就使用 crc32.IEEETable 或 crc32.NewIEEE()。不要看到都是 8 位十六进制就直接比较，先确认多项式、初始约定、输入范围和文本格式。

ieee := crc32.NewIEEE() // 等价于使用 crc32.IEEETable
crc32c := crc32.New(crc32.MakeTable(crc32.Castagnoli))

_, _ = ieee.Write([]byte("same bytes"))
_, _ = crc32c.Write([]byte("same bytes"))

fmt.Printf("IEEE=%08x CRC32C=%08x\n", ieee.Sum32(), crc32c.Sum32()) // 两种结果不可混用

还要明确 CRC-32 的用途：它适合发现传输或存储中的意外误码，不适合证明数据没有被恶意篡改。面对不可信来源，需要根据威胁模型使用 SHA-256、HMAC 或数字签名，而不是把 CRC-32 当成安全认证。

可复用函数应该返回哪些信息

实际项目里，我更愿意让函数同时返回 CRC、已读取字节数和错误。这样调用方可以核对文件大小，也能在 I/O 中断时知道处理到了哪里。若对关闭错误有严格要求，可以把 Close 放到命名返回值或调用方中单独处理；纯读取常见场景仍以读取错误为主要判断。

一份稳妥的调用清单是：

• 打开文件失败立即返回；
• 全程复用同一个 hash.Hash32 和同一张 Table；
• 检查 io.Copy 或手动 Read 的错误；
• 使用 Sum32 取得数值，用 %08x 输出固定宽度；
• 与外部结果比较前确认多项式和输入范围；
• 不要用 CRC-32 替代密码学完整性验证。

常见问题

分块大小会改变 CRC-32 结果吗

不会。只要所有字节按相同顺序、使用同一张 Table 写入同一个状态，64 KiB、256 KiB 或 io.Copy 的内部缓冲都应得到相同结果。块大小影响的是 I/O 行为和资源使用，不是校验算法的逻辑输入。

调用 Sum32 后还能继续 Write 吗

可以。hash.Hash 的 Sum 不改变底层状态，Sum32 也用于读取当前 32 位结果。继续写入会在已有状态上追加数据；如果要重新计算另一份独立内容，应先 Reset 或创建新对象。

可以并发把多个文件块写进同一个 Hash32 吗

不要直接并发写同一个实例。CRC 依赖字节顺序，多块并发完成的先后可能破坏原始顺序，而且接口没有承诺可并发使用。最简单可靠的做法仍是按文件顺序串行写入。

总结

大文件 CRC-32 的核心不是“把文件切成多少块”，而是让所有块按顺序进入同一个校验状态。默认用 crc32.New 加 io.Copy；要进度、限速或缓冲复用时手动读取；数据本来就在内存里再用 Checksum；只维护数值状态时考虑 Update。最后别忘了，能否正确对比结果首先取决于双方使用的多项式和输入约定一致。