本地 MySQL 环境连接问题排查与解决笔记

本地 MySQL 环境连接问题排查与解决笔记

本文档记录了从命令行环境配置到数据库成功连接的全流程排查，覆盖了 MySQL 新版本中常见的几个关键问题。

---

第一章：命令行环境问题

问题：mysql 命令提示"不是内部或外部命令"

• 现象: 在 CMD 或 PowerShell 中输入 mysql 后，系统报错，无法识别该命令。
• 根本原因: Windows 的 Path 环境变量设置错误。Path 应该包含可执行文件所在的 目录，而不是可执行文件本身。
  • 错误设置: E:\mysql\bin\mysql.exe
  • 正确设置: E:\mysql\bin
• 解决方案:
  1. 进入"系统环境变量"设置。
  2. 编辑"系统变量"中的 Path。
  3. 将错误的路径修正为正确的目录路径 E:\mysql\bin。
• 关键操作: 关闭所有已打开的命令行窗口，然后重新打开一个新的窗口，让新的环境变量生效。

---

第二章：数据库连接授权问题

问题 1: SQL 语法错误 ERROR 1064 (42000)

• 现象: 执行 SQL 命令时，提示语法错误。

• 常见原因: 命令拼写错误，例如将 CREATE 误写为 EATE。

• 解决方案: 仔细检查 SQL 关键字的拼写。

  正确示例：创建用户并授权

  -- 1. 创建用户 (请将 'root' 和密码 'root' 替换为您的配置)
  CREATE USER 'root'@'%' IDENTIFIED BY 'root';-- 2. 授予所有权限
  GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION;-- 3. 刷新权限使之生效 (关键步骤)
  FLUSH PRIVILEGES;
  

问题 2: Host '主机名' is not allowed to connect to this MySQL server

• 现象: 应用程序连接数据库时，连接被服务器拒绝。
• 根本原因: 出于安全考虑，MySQL 的用户账户默认只允许从特定的主机（如 localhost）登录。当您使用计算机名（如 DESKTOP-E9Q40LG）或 IP 地址连接时，该主机名/IP 未被授权。
• 解决方案: 创建一个允许从任意主机 (%) 或特定主机 ('DESKTOP-E9Q40LG') 登录的用户。上面的示例已使用 'root'@'%' 解决了此问题。

问题 3: Public Key Retrieval is not allowed

• 现象: 在解决了主机授权问题后，出现的新错误。

• 根本原因: 这是 MySQL 8.x 版本以上的新安全特性。默认的 caching_sha2_password 认证插件需要通过 RSA 公钥来加密密码。出于安全，客户端驱动默认 禁止 在非 SSL 的不安全连接上获取这个公钥。

• 解决方案: 修改应用程序的数据库连接 URL，明确告知驱动程序 “允许获取公钥”。

  Java (JDBC URL) 示例:

  jdbc:mysql://localhost:3306/dbname?allowPublicKeyRetrieval=true&useSSL=false
  

问题 4: Unknown database 'your_database_name'

• 现象: 连接参数正确后，提示找不到数据库。
• 根本原因: 连接 URL 中指定的数据库名称在服务器上实际不存在。
• 解决方案:
  • 方法一 (创建新库):

    CREATE DATABASE my_database;
    

  • 方法二 (使用旧库): 先查看已有哪些数据库，然后从列表中选择一个更新到您的连接 URL 中。

    SHOW DATABASES;
    

---

第三章：网络配置与最佳实践

核心知识点

• 主机名 vs IP: DESKTOP-E9Q40LG 是主机名，127.0.0.1 (本机) 和 192.168.X.X (局域网) 是 IP 地址。
• bind-address: MySQL 配置文件 (my.ini) 中的 bind-address 决定了 MySQL 服务监听 哪个 IP 地址 的连接请求。
  • 默认值/未设置: 127.0.0.1，只接受来自本机的连接。
  • 0.0.0.0: 监听所有网络接口，允许局域网或公网连接。

最佳实践

• 场景一：仅本机开发

  • 推荐做法: 在连接 URL 中直接使用 127.0.0.1 或 localhost 作为主机地址。这是最快、最稳定的方式。
  • my.ini 配置: 无需任何改动。

• 场景二：需要让局域网内其他设备连接

  1. 在 my.ini 的 [mysqld] 小节下，手动添加一行 bind-address = 0.0.0.0。
  2. 重启 MySQL 服务 使配置生效。
  3. 在连接 URL 中使用您电脑的局域网 IP 地址（例如 192.168.X.X）。

---

最终推荐的连接 URL 模板 (JDBC)

jdbc:mysql://<主机地址>:<端口号>/<数据库名>?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC

• <主机地址>: 推荐使用 127.0.0.1。
• <端口号>: 默认为 3306。
• <数据库名>: 替换为您真实存在的数据库名。
• useSSL=false: 避免不必要的 SSL 连接尝试。
• allowPublicKeyRetrieval=true: 解决公钥获取问题。
• serverTimezone=UTC: 推荐设置时区，避免时间相关的潜在错误。