SpringBoot连接MySQL时出现报错，如何快速排查和解决？

SpringBoot 连接 MySQL 报错的常见原因与解决方案

SpringBoot 作为 Java 微服务开发的主流框架，与 MySQL 数据库的集成是其核心功能之一，但在实际开发中，开发者常会遇到各种连接数据库的报错，本文将系统梳理这些问题的根源及解决方法，帮助快速定位和修复故障。

驱动依赖配置错误

现象：启动项目时抛出 ClassNotFoundException 或 NoClassDefFoundError，提示缺少 MySQL 驱动类（如 com.mysql.cj.jdbc.Driver）。
原因：未在项目中引入 MySQL 驱动依赖，或依赖版本与 MySQL 服务端不兼容。
解决方案：

1. 在 pom.xml 中添加 MySQL 驱动依赖（以 8.x 版本为例）：

   <dependency>  
       <groupId>mysql</groupId>  
       <artifactId>mysql-connector-java</artifactId>  
       <version>8.0.28</version> <!-- 与 MySQL 服务端版本匹配 -->  
   </dependency>  

2. 若使用旧版 MySQL（5.7 及以下），可将驱动改为 mysql-connector-java:5.1.49，避免版本冲突。

数据源配置参数错误

现象：启动后直接报 java.sql.SQLException，提示连接超时、认证失败或 URL 格式错误。
原因：application.properties/yaml 中数据库连接参数填写有误，包括 URL、用户名、密码等。
关键配置项检查：
| 配置项 | 示例值（MySQL 8.x） | 说明 |
|—————–|—————————-|————————–|
| spring.datasource.url | jdbc:mysql://localhost:3306/db_name?useSSL=false&serverTimezone=UTC | 端口默认 3306，需确认服务是否监听此端口；时区参数避免时区转换异常 |
| spring.datasource.username | root | 数据库用户名 |
| spring.datasource.password | your_password | 密码正确性验证 |
| spring.datasource.driver-class-name | com.mysql.cj.jdbc.Driver | 驱动类全限定名（8.x 版本） |

修正示例（application.yml）：

spring:  
  datasource:  
    url: jdbc:mysql://127.0.0.1:3306/test_db?characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai  
    username: admin  
    password: P@ssw0rd  
    driver-class-name: com.mysql.cj.jdbc.Driver  

MySQL 服务状态异常

现象：报错 Communications link failure 或 Connection refused。
原因：MySQL 服务未启动、端口被防火墙拦截，或服务端绑定地址限制客户端访问。
排查步骤：

1. 服务状态检查：通过命令行执行 systemctl status mysql（Linux）或任务管理器（Windows），确认 MySQL 进程运行正常。
2. 端口连通性测试：使用 telnet localhost 3306 或 nc -zv 127.0.0.1 3306 检查网络是否能到达 MySQL 监听端口，若失败，需开放防火墙规则（如 Linux 下执行 firewall-cmd --add-port=3306/tcp --permanent 并重启防火墙）。
3. 服务端配置验证：登录 MySQL 后执行 SHOW VARIABLES LIKE 'bind_address';，确保值为 0.0.0（允许所有 IP 访问）；若为特定 IP，需确认 SpringBoot 客户端的 IP 在允许列表内。

时区与字符集不匹配

现象：插入/查询数据时出现乱码，或报 The server time zone value is unrecognized。
原因：MySQL 时区设置与 JDBC 驱动解析不一致，或字符集编码不统一。
解决方案：

1. 时区配置：在 JDBC URL 中显式指定时区，如 serverTimezone=Asia/Shanghai；或在 MySQL 配置文件（my.cnf）中添加：

   [mysqld]  
   default-time-zone='+08:00'  

2. 字符集配置：URL 中添加 characterEncoding=utf8，并在 MySQL 配置中确保默认字符集为 utf8mb4：

   [mysqld]  
   character-set-server=utf8mb4  
   collation-server=utf8mb4_general_ci  

权限与账号问题

现象：报错 Access denied for user 'xxx'@'yyy'。
原因：数据库用户无对应 IP 的访问权限，或密码错误。
修复步骤：

1. 登录 MySQL 终端，执行：

   SELECT User, Host FROM mysql.user;  -- 查看用户权限  
   GRANT ALL PRIVILEGES ON db_name.* TO 'username'@'%' IDENTIFIED BY 'password';  -- 授予远程访问权限（% 表示任意 IP）  
   FLUSH PRIVILEGES;  -- 刷新权限  

2. 确认密码无误：可通过 MySQL 客户端工具（如 Navicat）测试账号密码能否登录。

连接池配置不当

现象：高并发场景下频繁报 Too many connections，或连接泄漏导致资源耗尽。
原因：HikariCP（SpringBoot 默认连接池）的 maxPoolSize、connectionTimeout 等参数设置不合理。
优化建议：
在 application.yml 中调整连接池参数：

spring:  
  datasource:  
    hikari:  
      maximum-pool-size: 20       # 最大连接数，根据业务负载调整  
      connection-timeout: 30000   # 连接超时时间（毫秒）  
      idle-timeout: 600000        # 空闲连接存活时间（毫秒）  
      max-lifetime: 1800000       # 连接最大生命周期（毫秒）  

相关问答 FAQs

A：通常是因为未添加 MySQL 驱动依赖，检查 pom.xml 是否包含 <dependency> 标签，且 groupId、artifactId、version 正确，若使用 Maven，可执行 mvn dependency:tree 查看 jar 包是否下载成功。

A：可能是 MySQL 服务端对“localhost”和“127.0.0.1”的解析方式不同（socket 连接 vs TCP 连接），尝试将 JDBC URL 改为 jdbc:mysql://127.0.0.1:3306/db_name，或检查 MySQL 用户表中该用户的 Host 字段是否包含“localhost”和“127.0.0.1”。