PHP 登录时怎么升级旧密码哈希

用户登录成功后，正是升级旧密码哈希的最好时机：明文密码只在这次请求里短暂可用，应用可以重新计算当前策略的哈希，再把数据库里的旧值替换掉。现代哈希用 password_verify() 验证后，再用 password_needs_rehash() 判断；如果数据库里还是自定义 MD5、SHA-1 或拼接盐格式，则必须先用原系统的准确规则验证，成功后立即改存 password_hash()。

先把“旧哈希”分成两条迁移路径

密码字段里常见两种数据。第一种是由 password_hash() 产生的自描述哈希，里面包含算法和 cost 等验证所需信息；第二种是早期系统自己拼出的摘要，例如固定长度的 SHA-1、MD5，或者“盐+密码”的自定义字符串。两者不能用同一套判断。

现代哈希要先验证，再判断是否重算

登录代码不要看到旧字符串就直接调用 password_hash()。正确顺序是先取出用户记录，用明文密码和存量哈希调用 password_verify()；只有返回 true，才说明这次登录确实拥有升级资格。之后再用当前算法和 options 调用 password_needs_rehash()。

这里的 $newHash 不应与旧哈希做字符串比较。密码哈希带随机盐，同一个密码再次计算也可能得到不同字符串；数据库字段也要能容纳未来默认算法变化，常见做法是使用足够宽的字符串列。

历史格式只能由原规则验证后一次性转换

如果 password_verify() 不通过，不能立即判定密码错误，因为它可能只是遇到了历史格式。应用必须按迁移前系统留下的规则验证，例如是否加盐、盐放在前面还是后面、是否做过多轮摘要。下面的函数只演示适配器位置，示例规则不是通用推荐算法，生产代码应替换为真实历史规则。

不要为了“兼容”继续新增旧格式，也不要根据字符串长度猜测算法。迁移完成后可以统计仍未登录的老账号，结合找回密码流程处理，而不是在后台批量猜测密码。

更新时保留旧值，避免并发登录互相覆盖

两个设备可能同时登录同一账号。两次请求都验证成功后，各自生成的随机盐不同；如果直接按用户 ID 更新，后完成的请求会覆盖先完成的结果。更稳妥的做法是把读取到的旧哈希也放入 WHERE，这是一种轻量的 compare-and-swap。

prepare($sql);
$stmt->execute([
    ':new_hash' => $newHash,
    ':id' => $userId,
    ':old_hash' => $storedHash,
]);

// 影响行数为 0 也不代表登录失败，可能是另一个请求已经完成升级。
$upgraded = $stmt->rowCount() === 1;
?>

升级写入失败时不要回滚刚刚已经确认的登录结果；可以记录一次脱敏事件并让用户继续使用当前请求。下一次登录仍会再次判断，直到更新成功。

上线前检查这份迁移清单

• 正确密码配合现代哈希可以登录，错误密码不会产生 UPDATE。
• 现代哈希的算法或 cost 变化会触发 password_needs_rehash()，但函数调用前已有 password_verify() 成功结果。
• 每种历史格式都有明确的版本标识或独立验证器，未知格式不会被猜测。
• 密码字段长度足够，日志不记录明文、完整哈希或可复原的盐。
• 并发登录测试确认旧值条件更新不会把较新的哈希覆盖掉。

相关问题

password_needs_rehash 可以直接判断 MD5 需要升级吗？

不能把它当作 MD5 验证器。它适合检查由密码哈希 API 产生的值是否符合当前算法和 options；MD5 等历史格式要先走原规则验证。

为什么不能把新哈希和旧哈希直接比较？

密码哈希通常包含随机盐，同一明文重复计算也会不同。登录验证应使用 password_verify()，不要自行重算后用字符串比较。

用户一直不登录，旧哈希怎么迁移？

没有明文密码就不能安全地把旧摘要转换成新哈希。应在下次成功登录或密码重置时迁移，不能在后台“反解”密码。