Spring Boot 连接 MySQL 失败常见报错原因和解决方法总结
作者：lazy H
摘要
在学习 Spring Boot 项目的过程中，连接 MySQL 是非常常见的一步。很多同学在配置数据库时，经常会遇到项目启动失败、控制台报红、接口无法查询数据等问题。常见报错包括 Communications link failure、Access denied for user、Unknown database、Cannot load driver class 等。本文将从项目结构、配置文件、MySQL 服务、账号密码、数据库是否存在、驱动依赖、URL 参数和远程连接权限等角度，总结 Spring Boot 连接 MySQL 失败的常见原因和解决方法。
一、前言
Spring Boot 项目本身可能没有问题，但是只要数据库连接配置有一个地方写错，项目就可能无法正常启动。对于初学者来说，控制台里一大片红色报错很容易让人慌，其实这类问题大多有固定排查顺序。
• MySQL 服务没有启动。
• 数据库地址、端口号、库名写错。
• 用户名或密码不正确。
• 数据库不存在。
• application.yml 缩进或配置项写错。
• MySQL 驱动依赖没有导入。
• JDBC URL 缺少时区、字符集等参数。
• 远程连接时 MySQL 没有开放权限。
二、先看一个正常的 Spring Boot + MySQL 配置
一个正常的 Spring Boot 数据库连接配置，通常需要项目中有 application.yml、pom.xml、启动类，以及数据库相关依赖。正常启动时，控制台一般能看到 Tomcat 启动成功和 HikariPool 连接池启动成功的日志。
图1 Windows / IDEA 风格：正常项目结构、application.yml 配置和启动日志
这里要重点看三个位置：第一是 resources 目录下的 application.yml，第二是 pom.xml 中的 MySQL 驱动依赖，第三是 Run 控制台里最后几行日志。如果最后显示 HikariPool 启动成功，说明数据库连接基本没问题。
三、原因一：MySQL 服务没有启动
如果 MySQL 服务没有启动，Spring Boot 项目连接数据库时就会失败。这个问题很常见，尤其是电脑刚开机后，MySQL 没有自动启动，或者自己手动停止过服务。
在 Windows 中可以通过“服务”窗口查看 MySQL80 是否为 Running，也可以在命令提示符中使用 sc query MySQL80 或 netstat 查看 3306 端口是否正在监听。
图2 Windows 风格：检查 MySQL80 服务和 3306 端口
解决方法很简单：如果 MySQL80 没有运行，就在服务窗口中右键启动，或者使用命令 net start MySQL80。启动后重新运行 Spring Boot 项目即可。
四、原因二：数据库地址或端口号写错
Spring Boot 连接 MySQL 时，最核心的是 JDBC URL。比如 jdbc:mysql://localhost:3306/springboot_demo 中，localhost 表示本机，3306 是 MySQL 默认端口，springboot_demo 是数据库名。
如果端口写错，比如把 3306 写成 3307，控制台就可能出现 Communications link failure。这个报错一般表示程序连不上 MySQL 服务。
图3 IDEA Run 控制台风格：端口错误导致 Communications link failure
排查时先确认 MySQL 是否启动，再确认端口号是否正确。默认情况下 MySQL 端口是 3306，如果自己安装时改过端口，就要以实际配置为准。
五、原因三：用户名或密码错误
如果 MySQL 能连接上，但是账号密码不对，就会出现 Access denied for user 这类报错。这个错误的意思很直接：当前用户没有通过 MySQL 的身份验证。
图4 IDEA Run 控制台风格：密码错误导致 Access denied for user
遇到这个问题时，优先检查 application.yml 中的 username 和 password。还要注意一点：如果密码中有特殊字符，最好用引号包起来，避免 yml 解析出问题。
六、原因四：数据库不存在
如果 application.yml 中写了某个数据库名，但是 MySQL 中没有这个数据库，启动时就会报 Unknown database。这个问题也很常见，尤其是导入别人项目时，代码里写好的库名和自己电脑里的库名不一致。
图5 IDEA Run 控制台风格：数据库不存在导致 Unknown database
解决方法是在 MySQL 中创建对应数据库，或者把 application.yml 中的数据库名改成自己本地已经存在的库名。学习项目中一般可以先创建一个简单数据库用于测试。
七、原因五：application.yml 缩进或配置项写错
application.yml 对缩进非常敏感，层级关系必须写对。比如 datasource 必须放在 spring 下面，并且缩进一般是两个空格。如果缩进错了，Spring Boot 可能读取不到数据库配置。
图6 IDEA 编辑器风格：application.yml 正确缩进和错误缩进对比
如果不确定 yml 是否写对，可以临时改用 application.properties，因为 properties 对缩进不敏感，例如 spring.datasource.url、spring.datasource.username、spring.datasource.password 分别写在三行即可。
八、原因六：MySQL 驱动依赖没有导入
Spring Boot 想连接 MySQL，必须有 MySQL 驱动依赖。如果 pom.xml 中没有 mysql-connector-j，或者 Maven 没有下载成功，就可能出现 Cannot load driver class、Cannot resolve symbol 等问题。
图7 IDEA Maven 面板风格：检查 MySQL 驱动依赖是否存在
如果依赖爆红，可以先点击 Maven 面板的 Reload All Maven Projects 重新加载。如果还是失败，再检查网络、Maven 镜像和本地仓库。
九、原因七：JDBC URL 参数不完整
有些 MySQL 版本连接时可能会提示时区、SSL 或字符集相关问题。学习项目中可以在 URL 后面补上常见参数，例如 useSSL=false、serverTimezone=Asia/Shanghai、useUnicode=true 和 characterEncoding=utf8。
图8 IDEA 编辑器风格：JDBC URL 中补充时区、字符集和 SSL 参数
如果控制台出现 server time zone value、SSL connection warning 等提示，可以优先检查 URL 参数。虽然这些不一定都会导致启动失败，但会影响连接稳定性和日志提示。
十、原因八：没有真正测试数据库连接
有时候项目启动成功，并不代表所有 SQL 都没问题。可以打开 MyBatis SQL 日志，或者写一个简单查询接口测试数据库是否真的能查到数据。
图9 IDEA 控制台风格：SQL 日志能帮助判断数据库是否真正连接成功
如果控制台能看到 Preparing、Parameters、Total 等日志，说明 SQL 已经执行到数据库了。此时如果查不到数据，就要继续检查表名、字段名、Mapper 映射和查询条件。
十一、原因九：远程连接 MySQL 权限不足
如果 Spring Boot 项目和 MySQL 不在同一台电脑上，问题会比本地连接更多。除了地址和端口，还要检查 MySQL 是否允许远程连接、服务器防火墙是否放行 3306、用户 host 权限是否正确。
图10 Windows / IDEA 风格：检查 MySQL 远程连接用户和 host 权限
学习阶段如果只是本机连接，url 写 localhost 即可。如果是连接云服务器或局域网数据库，就要把 localhost 改成服务器 IP，并确认 MySQL 配置允许远程访问。
十二、推荐排查顺序
连接 MySQL 失败时，不建议一上来就乱改代码。可以按照下面顺序检查，基本能覆盖大部分问题。
图11 Spring Boot 连接 MySQL 失败排查流程图
十三、常见报错和解决方法对照表
报错信息 | 常见原因 | 解决方法 |
Communications link failure | MySQL 服务没启动、端口写错、地址写错 | 启动 MySQL，检查 localhost 和 3306 |
Access denied for user | 用户名或密码错误，用户权限不足 | 检查 username、password 和用户权限 |
Unknown database | 数据库不存在或库名写错 | 创建数据库或修改 url 中的库名 |
Cannot load driver class | MySQL 驱动依赖缺失 | 检查 pom.xml 并刷新 Maven |
server time zone value | 时区参数缺失 | 在 URL 中添加 serverTimezone |
Public Key Retrieval is not allowed | MySQL 8 认证参数问题 | URL 中添加 allowPublicKeyRetrieval=true |
Connection refused | 服务没开或端口不通 | 检查服务、防火墙、端口监听 |
十四、总结
Spring Boot 连接 MySQL 失败时，最重要的是先看控制台最后几行报错。不要只看一大堆红色日志，而是重点找 Caused by、Communications link failure、Access denied、Unknown database 这类关键信息。
对于初学者来说，可以先记住一个简单顺序：先检查 MySQL 服务，再检查 url、端口、库名，然后检查账号密码，接着看驱动依赖和 yml 缩进，最后再考虑远程权限和 URL 参数。按照这个顺序排查，大多数数据库连接失败问题都能解决。
到此这篇关于Spring Boot 连接 MySQL 失败常见报错原因和解决方法总结的文章就介绍到这了,更多相关Spring Boot连接MySQL失败内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！