1. 准备工作：确保您的系统已安装必要的环境。
2. 安装驱动：使用 pip 安装 mysql-connector-python。
3. 验证安装：编写一个简单的 Python 脚本来测试连接。
4. 常见问题与解决方案：解决安装和使用中可能遇到的常见问题。

准备工作

在开始之前,请确保您已经具备以下两个条件：

a) 安装 Python

您的系统上需要安装 Python，您可以在终端或命令提示符中运行以下命令来检查：

python --version
# 或者
python3 --version

如果看到 Python 的版本号（Python 3.9.7），则表示已安装，如果没有，请先从 Python 官网 下载并安装。

b) 安装 MySQL 服务器

mysql-connector-python 是一个用于连接已存在的 MySQL 数据库服务器的驱动，您需要先安装并运行 MySQL 服务器。

• Windows: 您可以从 MySQL 官网 下载 MySQL Installer 进行安装。
• macOS: 使用 Homebrew 安装最为简单：brew install mysql
• Linux (Ubuntu/Debian): 使用 apt 安装：sudo apt update && sudo apt install mysql-server

安装完成后,请确保 MySQL 服务正在运行，并且您知道以下连接信息：

• 主机名: 通常是 localhost (如果数据库在本地)。
• 端口: 默认是 3306。
• 用户名: root。
• 密码: 您在安装 MySQL 时设置的 root 用户密码。
• 数据库名: 您想要连接的数据库的名称。

安装 mysql-connector-python 驱动

这是最关键的一步,我们将使用 Python 的包管理器 pip 来安装。

a) 打开终端/命令提示符

• Windows: 打开 "命令提示符" (CMD) 或 "PowerShell"。
• macOS / Linux: 打开 "终端" (Terminal)。

b) 使用 pip 安装

在终端中,输入以下命令并按回车：

pip install mysql-connector-python

如果您系统中有多个 Python 版本（Python 2 和 Python 3），为了避免冲突，建议使用 pip3：

pip3 install mysql-connector-python

c) 升级驱动（如果已安装）

如果您之前安装过旧版本,建议先升级到最新版本，以获得最新的功能和安全修复：

pip install --upgrade mysql-connector-python

安装完成后,您会看到类似 "Successfully installed mysql-connector-python-x.x.x" 的提示信息。

验证安装

安装成功后,我们编写一个简单的 Python 脚本来测试是否能成功连接到 MySQL 数据库。

创建一个名为 test_connection.py 的文件，并将以下代码粘贴进去。请务必修改其中的连接参数（用户名、密码、数据库名）以匹配您的配置。

import mysql.connector
from mysql.connector import Error
def connect_to_mysql():
    """连接到 MySQL 数据库"""
    try:
        # 尝试建立连接
        # --- 请根据您的实际情况修改以下参数 ---
        connection = mysql.connector.connect(
            host='localhost',          # 数据库主机地址
            database='your_database',  # 您要连接的数据库名
            user='your_username',      # 数据库用户名
            password='your_password'   # 数据库密码
        )
        if connection.is_connected():
            db_info = connection.get_server_info()
            print(f"成功连接到 MySQL 服务器，版本为: {db_info}")
            # 获取游标对象
            cursor = connection.cursor()
            # 执行一个简单的 SQL 查询
            cursor.execute("SELECT database();")
            record = cursor.fetchone()
            print(f"您正在连接的数据库是: {record[0]}")
    except Error as e:
        # 捕获并打印连接错误
        print(f"连接 MySQL 时发生错误: {e}")
    finally:
        # 确保连接被关闭
        if 'connection' in locals() and connection.is_connected():
            cursor.close()
            connection.close()
            print("MySQL 连接已关闭。")
# 调用函数
if __name__ == "__main__":
    connect_to_mysql()

如何运行脚本：

1. 保存文件 test_connection.py。
2. 在终端中,使用 cd 命令切换到该文件所在的目录。
3. 运行脚本：

   python test_connection.py

预期的成功输出：

成功连接到 MySQL 服务器，版本为: 8.0.29
您正在连接的数据库是: your_database
MySQL 连接已关闭。

如果看到 "连接 MySQL 时发生错误" 并提示 Access denied 或 Unknown database 等信息，请检查您的用户名、密码、数据库名是否正确，以及 MySQL 服务是否正在运行。

常见问题与解决方案

问题 1: pip 命令未找到

错误提示: 'pip' is not recognized as an internal or external command... 解决方案:

• Windows: 可能 Python 的安装路径没有被添加到系统的环境变量 PATH 中，您可以重新运行 Python 安装程序，在 "Advanced Options" (高级选项) 中勾选 "Add Python to PATH"。
• macOS / Linux: 尝试使用 python3 -m pip install ... 来代替 pip install ...。

问题 2: mysql.connector 模块未找到

错误提示: ModuleNotFoundError: No module named 'mysql.connector' 解决方案: 这通常意味着安装失败，请尝试以下步骤：

1. 升级 pip: python -m pip install --upgrade pip
2. 重新安装: pip uninstall mysql-connector-python (如果之前安装过)，然后再次 pip install mysql-connector-python。
3. 检查安装位置: pip show mysql-connector-python，查看安装路径是否在 Python 的模块搜索路径中。

问题 3: Access denied for user 'root'@'localhost'

错误提示: mysql.connector.errors.ProgrammingError: 1045 (28000): Access denied for user 'root'@'localhost' (using password: YES) 解决方案: 这表示用户名或密码错误，请仔细检查您在脚本中填写的用户名和密码是否与 MySQL 服务器中的配置完全一致，特别是密码，注意前后是否有空格。

问题 4: Can't connect to MySQL server on 'localhost'

错误提示: mysql.connector.errors.InterfaceError: 2003: Can't connect to MySQL server on 'localhost' (10061) 解决方案: 这通常表示无法连接到 MySQL 服务器，请检查：

1. MySQL 服务是否正在运行:
   • Windows: 打开 "服务"，找到 "MySQL" 相关服务，确保其状态为 "正在运行"。
   • macOS: brew services list 查看 mysql 状态。
   • Linux (Ubuntu): sudo systemctl status mysql 查看 mysql 服务状态。
2. 主机名和端口是否正确: 默认主机是 localhost，端口是 3306，如果您修改了默认端口，请确保在连接字符串中也指定了正确的端口，port=3307。

替代方案：PyMySQL

除了官方的 mysql-connector-python，还有一个非常流行的第三方库叫做 PyMySQL，它的 API 与 mysql-connector-python 略有不同，但同样好用。

安装 PyMySQL

pip install PyMySQL

PyMySQL 连接示例

import pymysql
# 连接配置
connection = pymysql.connect(
    host='localhost',
    user='your_username',
    password='your_password',
    database='your_database',
    cursorclass=pymysql.cursors.DictCursor  # 以字典形式返回结果，更方便
)
try:
    with connection.cursor() as cursor:
        # 创建一个新用户
        sql = "INSERT INTO `users` (`email`, `password`) VALUES (%s, %s)"
        cursor.execute(sql, ('webmaster@example.org', 'very-secret'))
    # 提交事务
    connection.commit()
    with connection.cursor() as cursor:
        # 读取数据
        sql = "SELECT `id`, `email` FROM `users` WHERE `email` = %s"
        cursor.execute(sql, ('webmaster@example.org',))
        result = cursor.fetchone()
        print(f"找到用户: {result}")
finally:
    connection.close()

• 首选官方驱动: mysql-connector-python 是 MySQL 官方维护的，与服务器版本兼容性最好，功能也最全面。
• 安装简单: 使用 pip install mysql-connector-python 一条命令即可。
• 关键在于配置: 连接失败时，90% 的问题都出在用户名、密码、数据库名、服务器是否运行等基础配置上。
• 测试验证: 编写一个简单的连接测试脚本是验证安装和配置是否正确的最佳方式。

希望这份详细的指南能帮助您顺利完成安装！