不能直接用 std::hash 处理大文件，因其为小对象设计、不支持流式读取，且全量加载易导致 OOM；应采用增量哈希如 xxHash，因其单头文件、零 malloc、跨平台、SIMD 加速且编译友好。
为什么不能直接用 std::hash 处理大文件
std::hash 是为小对象设计的，不支持流式读取；对 GB 级文件直接 std::ifstream::read 到内存会 OOM。真正要用的是增量哈希（incremental hash），比如 openssl 的 EVP_DigestUpdate 或 xxHash 的 XXH3_64bits_update。跨平台意味着不能依赖 Windows 的 CryptHashData 或 macOS 的 CC_MD5，得选有 C API、静态链接友好的库。
选 xxHash 而不是 OpenSSL 的三个实际原因
OpenSSL 的哈希接口线程安全但初始化开销大，每次新建 EVP_MD_CTX 都要调 EVP_DigestInit_ex；而 xxHash（v0.8+）的 XXH3_state_t 可复用、无 malloc、支持 64/128-bit 输出，且在 ARM64 和 x86-64 上都有 SIMD 加速。更重要的是：它单头文件（xxhash.h），CMake 中只需 add_library(xxhash INTERFACE) + target_include_directories，不用处理 OpenSSL 的动态链接或证书路径问题。
- 编译时加
-DXXH_INLINE_ALL让所有函数内联，避免符号冲突 - 分片大小建议设为
1 （64KB）——太小增加函数调用开销，太大降低缓存局部性 - 不要用
XXH3_64bits()一次性哈希整个文件，它内部仍会分块，但无法控制缓冲区和错误恢复
分片哈希类的关键成员与 RAII 设计
核心是把状态封装进类，避免裸指针和手动 XXH3_createState()/XXH3_freeState()。构造函数必须完成状态初始化，析构自动清理；同时支持移动（禁用拷贝），因为 XXH3_state_t 不可复制。
class ShardHash {
XXH3_state_t* state_;
public:
ShardHash() : state_(XXH3_createState()) {
if (!state_) throw std::runtime_error("XXH3_createState failed");
XXH3_64bits_reset(state_);
}
~ShardHash() { XXH3_freeState(state_); }
ShardHash(ShardHash&& o) noexcept : state_(o.state_) { o.state_ = nullptr; }
ShardHash& operator=(ShardHash&& o) noexcept {
if (this != &o) {
XXH3_freeState(state_);
state_ = o.state_; o.state_ = nullptr;
}
return *this;
}
void update(const void* data, size_t len) {
XXH3_64bits_update(state_, data, len);
}
uint64_t digest() const { return XXH3_64bits_digest(state_); }
};
跨平台文件读取与错误处理要点
Windows 下用 FILE* 比 std::ifstream 更可控（避免 locale 导致的 seekg 错误）；Linux/macOS 同样兼容。关键不是“怎么打开”，而是“怎么保证每次读精确 chunk_size 字节，且最后不足时不出错”：
立即学习“C++免费学习笔记（深入）”；
- 用
fread(ptr, 1, chunk_size, fp)，检查返回值是否等于chunk_size或剩余字节数 - 遇到
ferror(fp)必须立即 break，feof(fp)只在循环末尾判断 - 大文件可能被其他进程截断，读到 0 字节且未到 EOF 时应视为 I/O 错误
- Windows 上记得用
fopen(path, "rb")，否则换行符会被转换，哈希值错乱
分片计算本身不难，难的是让每一块的读取稳定、可中断、可续算——真正的性能瓶颈从来不在哈希算法，而在磁盘寻道和系统调用开销。如果需要更高吞吐，得上 posix_fadvise（Linux）或 PrefetchVirtualMemory（Windows），但这已超出“跨平台”的底线要求。
