手动构建merkle树易出错，核心坑在叶子对齐、哈希顺序、末块填充、字节序统一、标识字节防碰撞、分块读取防oom、span安全处理、哈希判等用sequenceequal、动态算树高、区分文件集合与单文件分块预处理、路径方向与实例生命周期管控。
用 MerkleTree 类手动构建文件块哈希树容易出错
直接手写树结构+递归哈希拼接，90% 的坑都出在叶子节点对齐和哈希顺序上。比如两个文件块分别算出 SHA256，拼接时没强制字节序（小端/大端），或没统一用 BitConverter.GetBytes() 转换，导致同一组数据在不同机器上生成不同父节点哈希。
更常见的是：把文件按固定大小切块后，最后一块不足长度却没做填充或特殊标记，导致不同大小文件的末尾块哈希被误认为相同——这会让整棵树校验失效。
- 始终用
Span<byte></byte>处理块数据，避免String编码引入不可见字符 - 叶子节点哈希前，先写入一个唯一标识字节（如
0x00），内部节点写0x01，防止“A+B”和“AB”哈希碰撞 - 不要依赖
File.ReadAllBytes()加载大文件——内存爆掉前就 OOM 了，改用FileStream+BufferedStream分块读
System.Security.Cryptography 不提供现成 Merkle 树实现
.NET 原生类库里没有 MerkleTree、BuildMerkleRoot 这类 API，SHA256.Create() 只负责单次哈希，不管理树形结构、也不处理双哈希拼接逻辑。有人试图用 HashAlgorithm.TransformBlock() 模拟，结果发现它不支持“把两个哈希值再哈希”，纯属误解接口用途。
真正能用的只有底层哈希器，其余全得自己组织：
- 用
List<byte></byte>存叶子哈希，别用string（Base64 后长度不固定，无法直接拼） - 合并两个哈希时，必须用
new Span<byte>(leftHash).SequenceEqual(new Span<byte>(rightHash))</byte></byte>判等，而不是.Equals()（引用比较） - 树高计算别硬编码：
(int)math.Ceiling(Math.Log(leafCount, 2))，否则 1 个文件块时根就是它自己，3 个块时第二层只剩 2 个节点，要补一个重复哈希
文件集合 Merkle 根 vs 单文件分块 Merkle 根，输入预处理完全不同
前者是对每个完整文件先算一次哈希（如 SHA256.HashData(fileBytes)），再把这些哈希当叶子；后者是把一个大文件切成 N 块，每块单独哈希。混淆这两者会导致“改了一个文件里的字节，但 Merkle 根完全不变”——因为你在集合模式下只改了文件内容，却没重新计算那个文件的顶层哈希。
典型错误场景：
- 用
Directory.GetFiles()获取路径列表，但没按字典序排序就直接喂给叶子数组 → 目录顺序不同，根哈希就不同 - 对文件集合做 Merkle 树时，漏掉了空文件（长度为 0），其哈希应为
SHA256.HashData(Array.Empty<byte>())</byte>，而非跳过 - 单文件分块时，块大小设为 64KB，但没考虑
FileStream.Read()实际返回字节数可能小于请求值（尤其最后一块），导致哈希计算基于未初始化内存
验证 Merkle 路径时，ComputeHash 调用次数和顺序决定成败
验证某一块是否属于树，不是拿它的哈希去查表，而是从叶子出发，按路径上给出的兄弟哈希逐层向上重算。最容易错的是方向：左兄弟在前还是右兄弟在前？如果路径约定是“当前节点在左，则提供右兄弟哈希”，那代码里就必须严格 hash = SHA256.HashData(rightSibling.Concat(currentHash))，反过来就全错。
还有个隐形雷：SHA256.Create().ComputeHash() 是有状态的，重复调用会累积数据。每次必须新建实例，或用 using var h = SHA256.Create(); 包裹。
- 路径数组（
IEnumerable<byte></byte>）必须和实际树结构严格对应，少一个、多一个、顺序颠倒，最终根哈希必不匹配 - 测试时别只用 2 个文件/块——至少覆盖 3 层树（7 个叶子），才能暴露拼接顺序和补零逻辑问题
- 输出 Merkle 根时，用
Convert.ToHexString(rootHash)，别用Encoding.UTF8.GetString()，后者对非文本字节会静默替换
验证路径那步，没人盯着哈希拼接顺序和实例生命周期，基本等于白做。