Python 标准库 hashlib 直至 3.12 才实验性支持 Argon2（仅 argon2i），生产环境必须用 argon2-cffi 等第三方库；其 PasswordHasher 自动处理盐、参数与编码，verify 失败必抛 VerifyMismatchError 异常。
为什么不能直接用 hashlib 调用 Argon2
Argon2 不在 Python 标准库的 hashlib 中，它是一个独立设计的现代密码哈希算法（2015 年密码哈希竞赛冠军），标准库直到 Python 3.12 才通过 hashlib 提供实验性支持，且仅限 argon2i 变体、无内存/线程参数控制。生产环境必须用成熟第三方实现。
当前最可靠的选择是 argon2-cffi（CFFI 绑定，稳定、广泛使用）或其轻量封装 argon2-cffi-bindings。别选已归档的 pyargon2 或纯 Python 实现（性能差、不推荐）。
安装与基础哈希：用 argon2.PasswordHasher 生成安全哈希
安装后，直接使用高层接口 argon2.PasswordHasher，它自动管理盐值、参数选择和编码格式（$argon2id$v=19$m=65536,t=3,p=4$... 这种字符串可直接存数据库）：
pip install argon2-cffi
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 默认参数（
m=65536内存 KiB，t=3迭代次数，p=4并行度）适合大多数 Web 应用，响应延迟约 100–300ms，兼顾安全与用户体验 - 不要手动指定盐——
PasswordHasher每次调用hash()都生成新随机盐，且已嵌入返回字符串中 - 哈希结果是完整字符串，含算法标识、参数、盐和校验和，验证时无需额外存储盐或参数
- 示例：
from argon2 import PasswordHasher
ph = PasswordHasher()
hash_str = ph.hash("user_password123") # 返回类似 "$argon2id$v=19$m=65536,t=3,p=4$..."
valid = ph.verify(hash_str, "user_password123") # True
验证失败时抛 VerifyMismatchError 而不是返回布尔值
ph.verify() 成功返回 True，但失败时**一定抛出 argon2.exceptions.VerifyMismatchError 异常**，不是 False。这是刻意设计：防止开发者写出 if not ph.verify(...) 这类忽略异常类型的错误逻辑，导致侧信道泄露（如响应时间差异暴露用户是否存在）。
正确写法必须用 try/except：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
from argon2.exceptions import VerifyMismatchError <p>try: if ph.verify(stored_hash, input_password):</p><h1>登录成功</h1><pre class="brush:php;toolbar:false;"> pass
except VerifyMismatchError:
密码错误（注意：这里和用户不存在应返回相同错误提示）
pass
常见错误现象：
- 直接写
if ph.verify(...) == False:—— 会触发未捕获异常，服务报 500 - 用
verify()结果做条件分支却没包try—— 生产环境一输错密码就崩 - 对不同错误（密码错 vs 用户不存在）返回不同 HTTP 状态码或消息 —— 给暴力枚举提供依据
需要自定义参数？用 argon2.low_level 控制内存、时间、并行度
当默认参数不满足场景（例如 IoT 设备内存紧张，或后台批处理需更高强度），必须切换到低层 API：argon2.low_level.hash_secret_raw() 或 .hash_secret()。这时你要自己选参数，并理解它们的实际影响：
-
memory_cost：以 KiB 为单位，典型值 65536（64 MiB）；降到 16384（16 MiB）会使哈希快约 4 倍，但抗 GPU 攻击能力显著下降 -
time_cost：迭代轮数，影响 CPU 时间；增加它比增加内存更易引发超时，建议优先调内存 -
parallelism：线程数，设为 CPU 逻辑核数较合理；超过 4–8 后收益递减，还可能挤占其他请求资源 - 必须显式传
salt（16 字节随机 bytes），否则哈希不可重现；可用os.urandom(16)
示例（不推荐日常用，仅当真有定制需求）：
import os from argon2.low_level import hash_secret <p>salt = os.urandom(16) hash_bytes = hash_secret( b"pwd", salt, time_cost=2, memory_cost=32768, # 32 MiB parallelism=2, hash_len=32, type=argon2.Type.ID )
真正容易被忽略的是：一旦用了自定义参数，所有验证逻辑也必须用同样参数调用 verify_secret()，且参数必须完全一致——数据库里只存哈希值不够，还得存当时用的 memory_cost 等元数据，否则无法升级或兼容旧数据。
