哈希验证必须基于完整写入磁盘后的文件，先关闭FileStream再用File.OpenRead或File.ReadAllBytes重新读取计算；服务端须提供可信哈希（如X-Content-SHA256），客户端需清洗前缀、解码Base64并比对字节数组；下载时应校验ContentLength、禁用自动重定向、避免CDN污染。
下载完成后立即计算文件哈希值
哈希验证必须基于**完整写入磁盘后的文件**，不能在流未关闭时读取。常见错误是边下载边哈希（如用 Stream.CopyTo 同时写入文件和计算哈希），这会导致哈希值不一致——因为文件可能尚未刷新到磁盘，或部分缓冲区未落盘。
正确做法是：先确保 FileStream 已关闭，再用 File.OpenRead 或 File.ReadAllBytes 重新读取文件计算哈希。小文件可用后者；大文件务必用前者配合 HashAlgorithm.ComputeHash 流式计算，避免内存暴涨。
- 用
using (var fs = File.OpenRead(filePath)) { hashAlg.ComputeHash(fs); } - 不要复用下载时的
HttpClient响应流——它可能已被释放或不可重读 - 推荐使用
SHA256（SHA256.Create()），比 MD5/SHA1 更安全且 .NET 内置无依赖
服务端需提供可信哈希摘要（非自行拼接）
哈希值必须由服务端在生成文件时同步计算并暴露，例如通过 HTTP 响应头 X-Content-SHA256、独立的 .sha256 文件，或 API 返回体中的 file_hash 字段。自行用“文件名+时间戳”拼接哈希字符串毫无意义，无法防篡改。
若服务端只返回 Base64 编码的哈希（如 sha256=base64encoded），需先解码：Convert.FromBase64String(hashBase64)，再与本地计算结果比较字节数组（SequenceEqual），不要比字符串。
- 警惕大小写和前缀干扰：服务端可能返回
sha256:xxx或SHA256=xxx，需清洗后再解析 - 避免用
string.Equals比较哈希字符串——Hex 编码可能含大小写混用，应统一转小写或直接比字节数组 - 如果服务端同时提供多种哈希（SHA256/SHA512），优先选 SHA256：兼容性好、性能适中、足够防碰撞
HttpClient 下载时如何避免截断或编码污染
默认 HttpClient.GetAsync 可能因响应头缺失 Content-Length 或网络中断导致文件写入不全，此时哈希必然失败——但错误原因不是哈希逻辑，而是下载本身不可靠。
必须启用完整性保障机制：
- 用
HttpResponseMessage.Content.ReadAsByteArrayAsync()获取完整字节后再写入文件（适合中小文件） - 大文件务必用
HttpCompletionOption.ResponseHeadersRead+ 手动流复制，并检查response.Content.Headers.ContentLength是否匹配实际写入字节数 - 禁用自动重定向（
AllowAutoRedirect = false），防止 302 跳转后丢失原始响应头中的哈希信息 - 设置合理的
Timeout和重试策略（如Polly），否则超时中断也会造成文件残缺
哈希不匹配时别急着重试，先查根本原因
哈希失败不等于网络问题。90% 的情况源于：服务端哈希计算方式与客户端不一致（如服务端对压缩包内文件哈希，客户端却对整个 zip 文件哈希），或客户端读取了带 BOM 的文本文件、隐藏的备用数据流（ADS）、NTFS 硬链接等非主数据。
调试建议：
- 用命令行工具交叉验证：
certutil -hashfile xxx.exe SHA256（Windows）或shasum -a 256 xxx.exe（macOS/Linux） - 检查文件长度是否与服务端声明的
Content-Length一致——不一致说明下载被截断 - 用十六进制编辑器打开文件，确认末尾无意外填充（如多出 0x00 或 HTML 错误页内容）
- 如果服务端提供的是分块上传后的合并文件哈希，客户端不能对单个分块哈希拼接
最易被忽略的一点：某些 CDN 或代理会在响应末尾注入脚本或注释，肉眼不可见但会改变哈希值。此时需对比原始源站直连的响应哈希。
