Go 实战：写一个并发 SHA-256 文件清单工具，目录扫描和结果核对一次讲清

要交付一份压缩包之前，最头疼的不是文件数量多，是根本说不清楚「现在这份和昨天那份到底有没有被人改动过」。几十个文件的时候还能手动核对大小，要是文件夹里存了几千份素材、配置文件和编译后的二进制包，最省心的方案就是先生成一份SHA-256清单，之后随时重新扫描一遍做比对就行。

这个小工具要解决什么

整个项目只做两件事：make 子命令会扫描指定文件夹生成 manifest.json，check 子命令读取旧的清单文件，重新扫描当前路径下的所有文件。清单里记录每个文件的相对路径、字节大小和SHA-256值，路径全部用斜杠格式存储，就算把清单从macOS拷贝到Linux下，也不会因为路径分隔符不一样导致全量误判。

先搭一个能跑的文件夹扫描骨架

新建项目文件夹之后执行下面两条命令，这里刻意没有引入任何第三方依赖：文件遍历、摘要计算和JSON输出全部用Go标准库实现，先把可用版本跑通，之后再考虑添加排除规则、处理符号链接或者更复杂的忽略文件逻辑。

mkdir sha-manifest && cd sha-manifest
go mod init example.com/sha-manifest

核心数据结构非常轻量，配合 json 标签处理之后生成的清单格式，既适合程序自动读取，后续对接CI流程或者自动交付脚本也很方便。

type Item struct {
    Path   string `json:"path"`
    Size   int64  `json:"size"`
    SHA256 string `json:"sha256"`
}

func hashFile(name string) (string, int64, error) {
    f, err := os.Open(name)
    if err != nil {
        return "", 0, err
    }
    defer f.Close()

    h := sha256.New()
    n, err := io.Copy(h, f)
    if err != nil {
        return "", 0, err
    }
    return hex.EncodeToString(h.Sum(nil)), n, nil
}

文件夹遍历和哈希计算不要混在同一个循环里

刚上手写逻辑的时候很容易在 filepath.WalkDir 回调里直接读取文件计算摘要，小文件夹场景下不会出问题，遇到网络挂载盘或者大量大文件的时候，整个遍历流程会被每一次磁盘读取操作卡住。更合理的分工方式是：遍历端把所有普通文件送入 jobs，固定数量的worker取任务读取文件完成计算，最后由单独的收集端统一汇总排序。

type job struct {
    abs string
    rel string
}

func scan(root string, workers int) ([]Item, error) {
    jobs := make(chan job, workers*2)
    results := make(chan Item, workers*2)
    errs := make(chan error, 1)
    var wg sync.WaitGroup

    for i := 0; i 

这里不用急着把worker数量设成CPU核心数的两倍，哈希是磁盘读取和运算结合的操作，机械硬盘、SSD、网络挂载文件夹的最优并发值差别很大，先用4作为基准值，再针对目标存储路径观察耗时和磁盘占用情况就行。这个工具的核心目标是实现可重复核对，不是直接把磁盘队列跑满。

把结果稳定写入manifest.json

排序是这个工具里很容易被漏掉的环节，worker返回结果的顺序本身就不确定，不做排序的话，两次生成操作得到的文件排列顺序完全不一样，放到Git里diff会表现得像是整个清单全量改动。排序之后再格式化加缩进写入，清单既能被程序正常读取，做代码评审的时候也可以直接查看内容。

func writeManifest(path string, items []Item) error {
    data, err := json.MarshalIndent(items, "", "  ")
    if err != nil { return err }
    return os.WriteFile(path, append(data, '\n'), 0o644)
}

运行之后得到的内容片段大致如下，摘要值会随文件内容变化，路径和大小字段能帮你第一时间判断是配置文件被改动，还是编译产物被重新生成过。

[
  {"path":"config/app.yaml","size":418,"sha256":"e3b0c442..."},
  {"path":"bin/api","size":12840960,"sha256":"5d7a0e91..."}
]

check模式该怎样给出有用的差异结果

复查操作不是简单比对两个JSON的字节流，把旧清单转成 map[string]Item，再重新扫描当前路径下的文件，就可以分别找出三类差异：旧清单里有但当前文件夹不存在的「缺失」文件，当前文件夹里多出来的「新增」文件，以及路径一致但大小或者摘要发生改动的「已修改」文件。输出的时候按路径排序，交付双方拿到报告之后很容易对齐核对。

func changed(old, now Item) bool {
    return old.Size != now.Size || old.SHA256 != now.SHA256
}

// 报告示例：
// MODIFIED config/app.yaml
// MISSING  bin/worker
// ADDED    docs/release.txt

有个边界场景需要提前注意：如果扫描的存储路径里刚好包含 manifest.json 本身，第二次生成清单的时候必然会得到不一样的摘要值。实际项目里建议把输出的清单放到扫描根文件夹之外，或者在遍历回调里主动跳过这个相对路径。临时文件、日志文件夹和构建缓存也可以通过明确的忽略列表排除，不要靠碰运气没出现对应文件名来规避问题。

本地验收：修改单个文件后重新跑check流程

准备一个包含 config/app.yaml 和 docs/release.txt 的测试文件夹，先生成基准清单，之后改动配置文件的内容再做核对。预期结果只会返回一条 MODIFIED config/app.yaml；如果返回了一堆无关的差异，先检查是不是把输出清单、日志或者编辑器临时文件也扫进去了。

go run . make ./sample -out ./baseline.json
printf '\nfeature: true\n' >> ./sample/config/app.yaml
go run . check ./sample -manifest ./baseline.json
# MODIFIED config/app.yaml

这个小项目很适合放在发布前校验、离线介质交付和备份抽检场景里。它不是完整的签名系统，也不能证明文件来源可信；它解决的只是「以某一份基线为准，后续文件有没有被改动」的可复查问题。

相关问题

SHA-256清单能替代代码签名吗？

不能。清单只能识别相对于基准的变化，如果基准清单本身被替换，工具不会有任何感知。需要身份和来源保证的时候，要搭配受控发布渠道、签名机制或者可信制品库一起使用。

为什么不直接比对文件修改时间？

修改时间可能会因为解压、复制或者版本控制操作发生变动，内容完全一致的文件也可能出现时间戳不一样的情况。摘要更适合判断内容是否改动，大小和修改时间只能作为辅助排查线索。

大文件夹场景下会不会占用太多内存？

当前示例会把所有条目留在内存里排序。如果要处理百万级别的文件，可以改成分批排序后归并的逻辑，或者搭配数据库、外部排序工具保存中间结果。

符号链接要不要计算目标文件的摘要？

建议默认先跳过。跟随链接很容易跳出当前扫描的根文件夹范围，甚至遇到循环引用的场景。确实需要处理链接的时候，要明确是记录链接本身还是目标文件的内容，同时加上根文件夹边界校验。

收尾检查

先把扫描、清单输出、单文件修改复查这三个动作跑稳定，再逐步添加忽略规则、多格式输出或者CI集成功能。这个迭代顺序比较稳妥：后续某次交付出现争议的时候，你手里至少有一份可重算、可定位、可解释的文件基准记录。