Go crypto/sha256 如何对大文件分块计算摘要

给一个几 GB 的文件计算 SHA-256，不需要先调用 os.ReadFile 把全部内容装进 []byte。更稳妥的做法是创建 sha256.Hash，让 io.Copy 持续把文件内容写入它，文件只按流读取，内存不会随着文件大小线性增长。

大文件摘要的关键是把文件当作流

sha256.Sum256 的参数类型是 []byte，调用方必须先拿到完整数据；它适合配置片段、请求体或已经存在内存中的小内容。文件可能远大于可接受的内存预算时，应该使用 sha256.New() 返回的 hash.Hash。这个对象实现了 io.Writer，每次写入都会继续推进同一个摘要状态。

因此，计算链路可以简化为：*os.File 是输入，hash.Hash 是输出，io.Copy 负责在两者之间搬运数据。这里的“分块”不要求业务代码手写一个固定大小的循环，标准库会以流式方式完成复制；如果确实要复用特定缓冲区，再选择 io.CopyBuffer。

用 io.Copy 计算文件 SHA-256

下面的函数返回十六进制摘要和实际读取的字节数。字节数不是装饰信息：它可以帮助调用方发现文件在读取前后发生了变化，也方便日志记录和传输核对。

package main

import (
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"io"
	"os"
)

// fileSHA256 流式读取文件，返回摘要和读取字节数。
func fileSHA256(path string) (string, int64, error) {
	// 只持有文件描述符，不把整个文件读进内存。
	f, err := os.Open(path)
	if err != nil {
		return "", 0, fmt.Errorf("打开文件失败: %w", err)
	}
	defer f.Close() // 函数返回时释放文件描述符。

	h := sha256.New()
	// h 是 io.Writer，io.Copy 会把文件内容持续写入摘要状态。
	n, err := io.Copy(h, f)
	if err != nil {
		return "", n, fmt.Errorf("读取文件失败: %w", err)
	}

	// Sum(nil) 只在完整读取成功后取出最终 32 字节摘要。
	return hex.EncodeToString(h.Sum(nil)), n, nil
}

func main() {
	sum, size, err := fileSHA256("./backup.tar")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Printf("bytes=%d sha256=%s\\n", size, sum)
}

函数里有三个重要边界。第一，os.Open 失败时不能继续创建摘要；第二，io.Copy 返回错误时，已经写入的字节数只能作为诊断信息，不能当成完整文件的摘要；第三，h.Sum(nil) 不会重置摘要状态，但应放在复制成功之后调用。

什么时候需要 io.CopyBuffer

如果程序已经维护了可复用的缓冲区，或者需要把多个复制任务的临时内存控制在一个预算内，可以这样写：

// buf 可在多个串行任务之间复用，避免反复申请临时空间。
buf := make([]byte, 128*1024)
h := sha256.New()
if _, err := io.CopyBuffer(h, file, buf); err != nil {
	return fmt.Errorf("计算摘要失败: %w", err)
}
sum := hex.EncodeToString(h.Sum(nil)) // 复制成功后再读取最终摘要。

CopyBuffer 的重点是复用调用方提供的缓冲区，不是改变 SHA-256 算法。缓冲区过大可能浪费内存，过小则可能增加调用次数；128 KiB 只是示例，实际应结合磁盘、网络文件系统和并发量压测。没有明确理由时，io.Copy 已经足够，先保持代码简单。

排查摘要不一致的检查清单

两台机器算出的值不同，先不要急着更换哈希算法。按下面顺序检查，通常能很快定位到输入边界：

1. 确认两次计算读取的是同一条路径和同一个文件版本。
2. 记录 io.Copy 返回的字节数，看看是否发生了截断或中途读取错误。
3. 确认没有把文本换行、字符编码或额外结尾字节在读取前改写。
4. 确保最终比较的是同一格式：原始 32 字节、十六进制小写字符串不能混用。

常见问题

io.Copy 会不会把整个文件放进内存？

不会。它连接的是 io.Reader 和 io.Writer，文件内容被持续写入摘要对象；业务代码不会得到一个完整文件切片。

为什么不能直接对文件调用 sha256.Sum256？

Sum256 接收 []byte，而文件是流。除非文件本来就已经在内存中，否则使用 sha256.New 配合 io.Copy 更合适。

摘要计算失败时能不能使用已经得到的部分结果？

不能把它当作完整文件摘要。错误返回时只应记录已读取字节数和错误原因，修复输入或读取链路后重新计算。

Go 官方文档对 sha256.New、Sum256 和 io.Copy 的接口边界有明确说明；实现文件摘要时，围绕“流式输入、成功后取值、错误可追踪”这三点组织代码即可。