libsodium 必须在所有加密操作前调用 sodium_init()，否则多数情况崩溃或静默失败；推荐程序启动时 main() 开头调用一次，它线程安全且仅首次生效。

libsodium 初始化必须在所有加密操作前调用

不初始化就直接用 sodium_init() 以外的函数（比如 crypto_secretbox_easy()），多数情况下会崩溃或返回错误，但不是总报错——有些平台静默失败，导致密文解不开却查不出原因。

• sodium_init() 是线程安全的，可以多次调用，但只首次真正初始化；建议在程序启动时尽早调用一次，比如 main() 开头
• 不要在每次加解密前重复调用，它内部有开销（如检测 CPU 指令集、初始化随机数生成器）
• 如果使用静态链接的 libsodium，某些旧版 macOS 或嵌入式环境可能因缺少 /dev/urandom 而卡住，此时需提前设置 sodium_set_misuse_handler() 捕获异常

对称加密选 crypto_secretbox 还是 crypto_aead_aes256gcm

别默认选 AES-GCM：libsodium 默认推荐 crypto_secretbox（XSalsa20-Poly1305），它更轻量、常数时间、无硬件依赖，且在绝大多数场景下足够安全。

• crypto_secretbox_easy() 适合大多数应用：传入密钥（crypto_secretbox_KEYBYTES 字节）、nonce（crypto_secretbox_NONCEBYTES 字节）、明文，输出带认证标签的密文
• crypto_aead_aes256gcm_encrypt() 仅当你需要与外部系统（如 TLS、Java Bouncy Castle）互操作，且明确要求 AES-GCM 时才用；它依赖 OpenSSL 或硬件 AES 指令，可移植性差
• nonce 绝对不能重用：对同一密钥，每个 nonce 必须唯一；建议用 randombytes_buf() 生成，别手写递增计数器（容易溢出或跨进程冲突）

密钥管理不能靠硬编码或字符串字面量

把密钥写成 "my-super-secret-key-123" 这种字符串，等于没加密。libsodium 不负责密钥派生，你得自己处理。

C++ Code Review Master

组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。

下载

• 用户口令 → 密钥：必须用 crypto_pwhash()（如 crypto_pwhash_str() + crypto_pwhash_str_verify()），而不是 MD5/SHA 简单哈希
• 主密钥派生子密钥：用 crypto_kdf_derive_from_key()，别用 XOR 或截断；它基于 HMAC-SHA512，支持上下文隔离
• 密钥存储：避免内存泄露——用完立即调用 sodium_memzero() 清零密钥缓冲区；别用 std::string 存密钥，改用 std::vector<unsigned char></unsigned> 或 unsigned char[]

编译链接时 -lsodium 顺序和运行时找不到符号

链接时报 undefined reference to 'crypto_secretbox_easy'，大概率不是没装库，而是链接顺序或符号可见性问题。

• 确保 -lsodium 放在源文件或目标文件之后：例如 g++ main.cpp -o app -lsodium，而不是 g++ -lsodium main.cpp -o app
• macOS 上若用 Homebrew 安装，头文件路径通常没问题，但动态库可能在 /opt/homebrew/lib，需加 -L/opt/homebrew/lib
• Linux 下静态链接要小心：如果同时链接了其他也用 libsodium 的第三方库（如 ZeroMQ），可能因 ABI 版本不一致导致运行时 symbol lookup error；建议统一用系统包管理器安装的版本，或全静态编译并确认 ldd app 不显示 libsodium

最常被跳过的一步是 nonce 生命周期管理——它和密钥一样关键，但没人记得存哪、怎么传、过期怎么处理。别把它当“随便填的参数”。

C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！