Go crypto/sha512 怎样计算文件摘要

我在给构建产物做完整性记录时，最常用的做法是让文件内容流过 crypto/sha512.New()，再把结果编码成十六进制字符串。这样不需要一次性把大文件读进内存，代码也能清楚地区分“读取失败”和“摘要不一致”两类问题。

官方文档：https://pkg.go.dev/crypto/sha512

计算文件 SHA-512 摘要的稳妥写法是：打开文件，创建 sha512.New()，用 io.Copy 把文件内容写入哈希对象，关闭文件后取出摘要。SHA-512 的原始结果是 64 字节，记录或比较时通常转换成 128 个十六进制字符。

下面的例子只围绕一个文件完成摘要计算。示例中的输出值应以实际文件内容为准，文件在读取期间如果被替换，摘要也会随读到的字节变化。

先确认 sha512 提供了哪些结果

crypto/sha512 同时提供流式构造函数和一次性数据函数。New() 返回一个实现了 hash.Hash 的 SHA-512 状态对象，适合通过 Write 或 io.Copy 持续接收数据；Sum512(data) 则适合手上已经有完整字节切片的场景。

标准 SHA-512 的结果长度由 sha512.Size 表示，值为 64 字节；转换为常见的十六进制文本后长度是 128 个字符。不要把 SHA-512、SHA-384 和 SHA-512/256 的输出长度混在一起，它们在同一个包里但用途和摘要尺寸不同。

用 io.Copy 流式读取文件

文件摘要的核心关系是“文件句柄提供输入，哈希对象维护状态”。我更倾向于用 io.Copy 连接二者：调用方不用自己维护缓冲区，文件大小变大时也不会因为一次性读取而额外占用同等规模的内存。

package main

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

// fileDigest 以流式方式读取文件，并返回 SHA-512 的十六进制摘要。
func fileDigest(path string) (string, error) {
	// 打开文件后由函数负责关闭，避免文件描述符一直占用。
	file, err := os.Open(path)
	if err != nil {
		return "", fmt.Errorf("打开文件失败: %w", err)
	}
	defer file.Close()

	// hash.Hash 保存中间状态，io.Copy 负责把文件字节持续写入它。
	digest := sha512.New()
	if _, err := io.Copy(digest, file); err != nil {
		return "", fmt.Errorf("读取文件并计算摘要失败: %w", err)
	}

	// Sum(nil) 返回当前状态的摘要字节，再编码成方便记录和比较的文本。
	return hex.EncodeToString(digest.Sum(nil)), nil
}

func main() {
	// 路径和输出只是调用示例，实际项目应从参数或配置中传入。
	sum, err := fileDigest("artifact.bin")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(sum)
}

这里的两个错误分支都返回了原始错误上下文：文件不存在、权限不足或读取中断，都不会被误判为“摘要不一致”。如果你的程序需要继续处理多个文件，可以在更外层记录路径并继续循环，而不是在底层函数里吞掉错误。

把摘要转换成可记录的文本

digest.Sum(nil) 返回当前哈希状态的字节切片，随后用 hex.EncodeToString 转成小写十六进制文本。这个文本适合放在清单文件、日志或配置中；如果要节省存储空间，也可以保留原始字节，但跨系统交换时十六进制更直观。

如果输入本来就是内存中的小字节切片，可以直接使用一次性接口：

data := []byte("hello, Go")

// Sum512 适合已经完整存在内存中的小数据，不需要额外创建哈希状态。
sum := sha512.Sum512(data)

// [64]byte 仍是定长字节数组，转成切片后再编码为十六进制文本。
text := hex.EncodeToString(sum[:])
fmt.Println(text)

两种接口的选择看输入形态：文件、网络响应或大型流使用 New 加持续写入；短字符串或已有的完整切片使用 Sum512 更简洁。不要为了配图或演示而把大文件先读成 []byte，那会失去流式读取的优势。

按字节比较期望摘要

摘要计算完成后，常见任务是判断文件是否仍与清单中的摘要一致。下面先把期望值从十六进制文本解码回字节，再进行长度和内容比较。用于普通构建产物校验时，直接比较字符串也可以；如果比较值参与安全敏感的认证流程，应使用常量时间比较，并先确认解码和长度都成功。

package main

import (
	"crypto/subtle"
	"encoding/hex"
	"fmt"
)

// sameDigest 比较十六进制摘要，并把格式错误与不匹配区分开。
func sameDigest(actualText, expectedText string) (bool, error) {
	actual, err := hex.DecodeString(actualText)
	if err != nil {
		return false, fmt.Errorf("实际摘要不是合法十六进制: %w", err)
	}
	expected, err := hex.DecodeString(expectedText)
	if err != nil {
		return false, fmt.Errorf("期望摘要不是合法十六进制: %w", err)
	}
	if len(actual) != len(expected) {
		return false, nil
	}

	// 常量时间比较适合不希望比较耗时随首个差异位置变化的场景。
	return subtle.ConstantTimeCompare(actual, expected) == 1, nil
}

如果只是本地缓存命中判断，下面这种写法也足够直观：

// 普通一致性检查直接比较规范化后的十六进制文本。
same := actualText == expectedText

更重要的是先统一格式：十六进制大小写、是否允许前后空白、摘要算法名称都应由协议或清单格式明确规定，不能一边生成小写值，一边拿未规范化的用户输入直接比较。

空文件和文件变化时要注意什么

空文件也有确定的 SHA-512 摘要，读取不到数据不等于读取失败。真正需要区分的是 io.Copy 是否返回错误，以及文件在计算期间是否被其他进程修改。

• 空文件：摘要仍然可计算，调用方不要用“字节数为零”替代摘要结果。
• 文件被替换：同一路径在打开前后可能指向不同内容；需要稳定快照时应由上层负责文件替换策略。
• 读取权限：打开失败和中途读取失败都应保留错误，不要返回一个看似合法的空摘要。
• 超大文件：优先使用流式方式，并在需要时配合限速、取消或上层超时管理。

什么时候应该换成其他摘要算法

SHA-512 适合完整性记录、内容寻址和跨系统比对，但它不是密码存储方案，也不能单独证明文件来自哪个发布者。如果需求是验证发布者身份，应结合数字签名和公钥分发；如果是存储用户密码，应使用专门的密码哈希方案，而不是直接调用 sha512.Sum512。

对于只需要固定长度、并且协议已经规定 SHA-256 的场景，应按协议使用对应算法。算法选择首先由对端格式和安全目标决定，不是单纯追求摘要越长越好。

常见问题

为什么文件摘要代码通常不用 os.ReadFile？

os.ReadFile 会把整个文件读入内存，适合小文件；对大型文件，sha512.New 配合 io.Copy 更容易控制内存占用。

sha512.Sum512 和 sha512.New 有什么区别？

Sum512 接收完整的 []byte 并返回定长 [64]byte；New 返回可持续写入的 hash.Hash，适合文件或其他流式输入。

摘要不一致时是不是一定是算法错了？

不一定。输入文件内容、读取时机、摘要算法、十六进制大小写和期望值来源都可能造成差异。应先确认两边使用相同的字节内容和算法，再检查文本规范化。

用 Go 计算文件 SHA-512 摘要时，记住三件事就够了：大文件走流式输入，结果用明确格式记录，错误和安全用途分开处理。这样既能保持实现简洁，也能避免把文件变化、格式问题误判成哈希库故障。