PHP 旧 MD5 密码如何平滑迁移到 password_hash：兼容登录与自动升级完整流程

很多老 PHP 项目都有一个历史包袱：用户表里的密码字段存的是 MD5。它看起来还能用，但安全性已经不适合继续作为登录密码方案。问题是，线上有大量老用户，不能简单地让所有人立刻重置密码。

这篇文章按一个完整迁移流程来走：先识别旧哈希格式，再做兼容登录，登录成功后自动写回新哈希，最后逐步减少旧格式占比。目标是让用户无感升级，同时让项目密码存储回到现代方案。

目标和边界：迁移不是一次性清库

先把边界定清楚。我们要处理的是用户表里已经存在大量 MD5 密码的老项目。迁移目标不是把数据库密码全部离线改掉，因为你不知道用户明文密码；也不是强制所有用户重置密码，因为这会影响登录转化和客服成本。

更合理的目标是：用户下一次正常登录时，如果旧密码校验通过，就把密码升级成 password_hash 生成的新哈希。这样活跃用户会自然完成迁移，不活跃用户可以后续通过重置密码补齐。

先说结论：登录成功时顺手升级最稳

完整流程可以概括成一句话：先判断数据库里存的是旧 MD5 还是新哈希；如果是新哈希，直接用 password_verify；如果是旧 MD5，先兼容校验，校验成功后立刻生成新哈希并写回用户表。

这个方案的好处是用户无感，代码路径也清楚。只要迁移期间保留兼容分支，就不会因为格式混用导致大面积登录失败。

全流程总览：旧 MD5 到 password_hash

下面这张图展示了核心路径：旧 MD5 用户登录成功后，会生成新哈希并写回用户表；下次登录就直接走新格式校验，不再走兼容分支。

阶段 1：识别旧格式和新格式

旧 MD5 通常是 32 位十六进制字符串，而 password_hash 生成的新哈希会带有算法前缀，例如 bcrypt 常见 $2y$，Argon2id 常见 $argon2id$。

function isModernPasswordHash(string $stored): bool
{
    return str_starts_with($stored, '$2y$')
        || str_starts_with($stored, '$argon2id$');
}

function isLegacyMd5Hash(string $stored): bool
{
    return strlen($stored) === 32 && ctype_xdigit($stored);
}

这一步不要只用长度判断新格式，因为以后算法可能调整。最好把“旧格式”和“新格式”的识别规则写成独立函数，后续收尾统计也能复用。

阶段 2：兼容校验登录密码

校验逻辑可以拆成两个分支：新格式直接用 password_verify，旧格式用 md5 的结果和存储值做安全比较。

function legacyMd5Matches(string $plain, string $stored): bool
{
    return isLegacyMd5Hash($stored)
        && hash_equals($stored, md5($plain));
}

function verifyPassword(string $plain, string $stored): bool
{
    if (isModernPasswordHash($stored)) {
        return password_verify($plain, $stored);
    }

    return legacyMd5Matches($plain, $stored);
}

注意，这里只是为了迁移期兼容旧数据，不是鼓励继续使用 MD5。新注册用户和新改密用户都应该直接写入新哈希。

阶段 3：登录成功后自动写回新哈希

真正完成迁移的是写回动作。旧格式校验成功后，马上生成新哈希，并更新用户表里的密码字段。

function verifyAndUpgradePassword(int $userId, string $plain, string $stored): array
{
    if (isModernPasswordHash($stored)) {
        return [
            'ok' => password_verify($plain, $stored),
            'new_hash' => null,
        ];
    }

    if (!legacyMd5Matches($plain, $stored)) {
        return [
            'ok' => false,
            'new_hash' => null,
        ];
    }

    return [
        'ok' => true,
        'new_hash' => password_hash($plain, PASSWORD_DEFAULT),
    ];
}

上面的函数只负责判断和生成新哈希，实际写库建议放到用户仓储或服务层里，避免登录控制器里混太多数据库细节。伪代码大概是这样：

$result = verifyAndUpgradePassword($user['id'], $plainPassword, $user['password']);

if (!$result['ok']) {
    return loginFailed();
}

if ($result['new_hash'] !== null) {
    savePasswordHash($user['id'], $result['new_hash']);
}

return loginSuccess($user);

阶段 4：统计旧格式占比并收尾

迁移上线后，不要立刻删除兼容逻辑。先统计还有多少用户停留在旧格式。例如每天统计一次旧 MD5 占比，观察自然登录迁移速度。

等旧格式占比很低以后，可以针对剩余用户做密码重置提醒。最终确认无旧格式数据后，再删除兼容分支，登录流程就只保留 password_verify。

容易踩坑

• 上线后立刻删除 MD5 分支：老用户会大面积登录失败。
• 写回新哈希没有事务保护：登录成功但写回失败时，要能记录并下次继续迁移。
• 新注册还在写 MD5：迁移期间必须先改新注册和改密逻辑。
• 把明文密码写日志：迁移排查时也不能记录用户明文密码。
• 只看用户总数：更应该看活跃用户中旧格式占比。

速查表

总结

PHP 老项目从 MD5 迁移到 password_hash，最稳的路线不是强制所有用户立刻改密码，而是在登录成功时自动升级。这样既不打断用户，也能让活跃账号逐步进入新方案。

上线时记住三件事：新注册和改密先改成新哈希；老用户登录保留兼容分支；迁移后持续统计旧格式占比。只要流程设计清楚，密码升级就能从一次高风险操作变成一条可控的渐进路径。