解决Python连接MySQL报错：Authentication plugin 'caching_sha2_password'

在使用 Python 连接 MySQL 数据库时，控制台突然抛出包含 Authentication plugin 'caching_sha2_password' 或 'cryptography' package is required for sha256_password or caching_sha2_password auth methods 的异常，通常是因为 MySQL 8.0 默认使用了更安全的 SHA-256 密码认证插件，而 Python 客户端环境缺少对应的解密算法库，或者客户端驱动版本较旧无法完成握手。解决这个问题的核心路径有两个方向：优先在 Python 运行环境中补齐 cryptography 依赖以保留高安全性；或者在特殊受限环境下将 MySQL 账号的认证规则切换回旧版的密码格式。

报错表现与根源分析

当开发者使用 pymysql、mysqlclient、mysql-connector-python 或通过 SQLAlchemy 建立数据库连接时，常见的报错信息主要分为两类：

# 常见报错表现 1（PyMySQL 提示缺失算法包）
RuntimeError: 'cryptography' package is required for sha256_password or caching_sha2_password auth methods

# 常见报错表现 2（驱动不支持该认证插件）
InternalError: (2059, "Authentication plugin 'caching_sha2_password' cannot be loaded: ...")

要彻底解决该问题，首先需要理解 MySQL 认证机制的演进。在 MySQL 5.7 及更早版本中，默认的用户密码认证插件是 mysql_native_password，它采用双重 SHA-1 哈希算法，客户端无需复杂的公钥加密即可完成鉴权。而从 MySQL 8.0 开始，官方为了防御彩虹表破解和中间人窃听，将默认认证插件升级为 caching_sha2_password。该插件结合了加盐 SHA-256 哈希、内存缓存提速以及 RSA 非对称公钥交换机制。

当 Python 客户端向 MySQL 8.0 发起握手请求时，若当前连接未开启 TLS/SSL 加密，服务端会要求使用 RSA 公钥对密码进行安全封包。此时如果 Python 环境中没有安装负责加解密底层实现的 cryptography 库，Python 驱动便无法解析 RSA 密钥对，从而直接中断握手并抛出异常。

图 1：MySQL 5.7 与 MySQL 8.0 认证机制演进及 Python 驱动依赖差异

排查思路与方案选择

面对此报错，不要盲目去修改数据库服务器的全局配置。根据具体的系统权限与部署环境，我们可以按照清晰的决策流程来确定最具性价比的解决路径：

图 2：问题排查与技术路线选择逻辑图

方案一：安装 cryptography 依赖库（官方推荐）

这是最标准、最安全的解决方案。它不需要对数据库服务器上的账号权限、密码规则或全局配置做任何破坏性修改，完全在 Python 客户端本地解决问题。

1. 安装依赖命令

根据你正在使用的 Python 虚拟环境（如 venv、conda 或 Poetry），激活对应的虚拟环境后运行以下命令：

# 激活虚拟环境后运行（建议同时更新 pip）
pip install --upgrade pip
pip install cryptography

如果你使用的是 PyMySQL 库，PyMySQL 从较早版本起就支持将 rsa 模块作为其扩展功能打包安装，你也可以直接执行：

# 安装带有 RSA 加密扩展支持的 PyMySQL
pip install "pymysql[rsa]"

2. 为什么安装后能直接解决

当 cryptography 安装完成后，PyMySQL 内部的 _auth.py 模块在处理 caching_sha2_password 时，就能够通过 OpenSSL 底层算法库读取 MySQL 服务端下发的 RSA 公钥，并将客户端提交的密码正确加密发送给服务端进行匹配。整个认证流平滑打通，同时享受到了加盐哈希带来的防碰撞保护。

图 3：客户端补齐 cryptography 依赖标准操作步骤

方案二：修改 MySQL 用户认证方式为 mysql_native_password

在某些极其受限的场景中，比如嵌入式设备、无法联网下载二进制 wheel 包的老旧 Linux 机器、缺少 C 编译器构建环境的容器中，安装 cryptography 可能会遇到编译报错（例如提示缺少 Rust 编译器或 OpenSSL 头文件）。

此时，如果你拥有 MySQL 的管理员（如 root）权限，可以选择将目标业务账号的认证插件降级为旧版的 mysql_native_password。这样 Python 客户端就可以使用最简单的 SHA-1 双重散列算法登录，而完全不再需要本地具备 RSA 计算能力。

1. 登录 MySQL 命令行控制台

以管理员身份进入 MySQL：

mysql -u root -p

2. 查看当前用户的认证插件

通过查询 mysql.user 系统表确认该用户当前的认证插件类型：

SELECT user, host, plugin FROM mysql.user WHERE user = 'myuser';

你将看到该账号对应的 plugin 列内容为 caching_sha2_password。

3. 修改用户认证插件并刷新权限

使用 ALTER USER 语句将认证方式变更为 mysql_native_password，并重设密码：

-- 将用户 myuser 的认证插件更改为 mysql_native_password
ALTER USER 'myuser'@'%' IDENTIFIED WITH mysql_native_password BY 'YourStrongPassword123!';

-- 刷新系统权限表使修改立即生效
FLUSH PRIVILEGES;

方案三：检查并升级 Python 数据库驱动库

除了依赖缺失外，部分老旧项目使用的驱动版本过低也是导致该报错的常见原因。例如：

• PyMySQL：若版本低于 0.9.3，对 MySQL 8.0 的握手协议支持不完整。建议升级到 1.0.0 以上：pip install --upgrade pymysql。
• mysql-connector-python：如果是 Oracle 官方驱动，建议版本保持在 8.0.20 及以上。连接时可以显式指定开启公钥检索或使用 SSL。

配置连接参数（公钥检索配置）

在未配置 SSL 证书的开发环境中，PyMySQL 和官方 Connector 还支持在连接参数中声明允许向服务端检索公钥：

# PyMySQL 传递 client_flag 或配置参数
import pymysql

connection = pymysql.connect(
    host='127.0.0.1',
    user='myuser',
    password='YourStrongPassword123!',
    database='testdb',
    charset='utf8mb4',
    cursorclass=pymysql.cursors.DictCursor
)

完整验证与连接测试代码

在完成上述任一修复操作后，编写一个最小化的 Python 脚本进行连通性验证。确保能够在控制台正确获取数据库版本号与当前连接会话的插件类型。

import pymysql

def verify_mysql_connection():
    try:
        conn = pymysql.connect(
            host="127.0.0.1",
            port=3306,
            user="myuser",
            password="YourStrongPassword123!",
            database="information_schema",
            charset="utf8mb4"
        )
        with conn.cursor() as cursor:
            # 查询数据库版本
            cursor.execute("SELECT VERSION();")
            version = cursor.fetchone()
            print("✔ 连接成功！MySQL 服务器版本:", version[0])
            
            # 查询当前用户的实际认证插件
            cursor.execute("SELECT CURRENT_USER(), @@default_authentication_plugin;")
            auth_info = cursor.fetchone()
            print("✔ 当前会话用户及默认插件:", auth_info)
            
        conn.close()
    except Exception as e:
        print("✕ 仍然报错，详细信息如下:")
        print(type(e).__name__, ":", e)

if __name__ == "__main__":
    verify_mysql_connection()

运行该脚本后，若输出类似 ✔ 连接成功！MySQL 服务器版本: 8.0.32，则表明鉴权握手已经顺利通过，应用程序可以正常执行数据读写操作。

图 4：技术方案选型对比与上线部署检查清单

总结

遇到 Authentication plugin 'caching_sha2_password' 报错时，最优雅的解决策略始终是在 Python 环境中直接安装 cryptography 依赖（或通过 pip install "pymysql[rsa]" 一并安装）。这一做法完全契合 MySQL 8.0 的安全演进策略，无需降低数据库账户安全等级，也无需调整服务端配置。只有在极少数无法编译安装加密包的极端特殊环境中，才考虑使用 ALTER USER ... IDENTIFIED WITH mysql_native_password 降级插件作为临时过渡方案。