先问一句你手上是不是还留着 mysql-connector-java-5.1.49.jar如果你已经把服务端升级到 MySQL 8.0却还在用这套老驱动那我敢说各种奇奇怪怪的报错你一定见了不少一会是Public Key Retrieval is not allowed一会是Server returns invalid timezone再不然就是ClassNotFoundException: com.mysql.jdbc.Driver。这些十有八九都不是服务器问题而是 MySQL 8.0 的 JDBC 驱动没跟上。今天就把 MySQL 8.0 版本 JDBC 驱动 Jar 包的选型、下载、参数配置还有我实际踩过的坑一次性讲清楚。这篇文章适合正在做服务升级、新项目初始化或者半夜被“连不上数据库”电话叫醒的 Java 开发者看完能少走不少弯路。1. 为什么 MySQL 8.0 不能用老驱动1.1 MySQL 8.0 的认证方式已经变了很多人以为 JDBC 驱动只是个“翻译器”新旧无所谓这恰恰是问题核心。MySQL 8.0 默认的认证插件从mysql_native_password换成了caching_sha2_password。老驱动尤其是 5.1.x 系列握手协议还停留在以前那一套它不认识caching_sha2_password这个插件于是客户端和服务端之间就“说不上话”。最典型的表现就是启动项目时报错java.sql.SQLException: Unable to load authentication plugin caching_sha2_password这问题不是把数据库用户改回mysql_native_password就能一劳永逸的。虽然这种兼容做法在很多老项目里确实存在但如果你新建数据库、新建账户都用了 MySQL 8.0 的默认配置那么驱动版本不升级坑会一直存在。我这里不是说不允许用兼容插件而是提醒你该升级的驱动一定要升级别把兼容当长期方案。1.2 驱动类名和 Maven 坐标都变了JDBC 驱动不是“换个 jar 包就完事”驱动类名也跟着变了。旧版用的是com.mysql.jdbc.DriverMySQL 8.0 官方驱动改成了com.mysql.cj.jdbc.Driver。如果项目里还写着老的类名启动时大概率会看到ClassNotFoundException: com.mysql.jdbc.Driver另外 Maven 坐标也有变化。早期版本坐标是dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version8.0.33/version /dependency后面的官方坐标改成了com.mysql:mysql-connector-jdependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId version8.0.33/version /dependency两种坐标在官方仓库里都能找到但我建议新项目直接采用新坐标老项目升级时也要把坐标和类名一起改掉别只换 jar 不换参。1.3 新驱动带来的协议和时区断言MySQL 8.0 驱动重新实现了连接协议并且在连接阶段增加了时区校验。以前用 5.x 驱动连 MySQL 5.7jdbc:mysql://localhost:3306/demo这样写基本没问题现在用 8.0.x 驱动如果你不在 URL 上显式指定serverTimezone就会直接给你抛一个异常说服务端时区值无法识别。很多人第一次升级到 8.0 驱动时第一个撞墙就是这个。2. 三条路拿到 MySQL 8.0 JDBC 驱动 Jar 包2.1 用 Maven 或 Gradle 统一管理依赖这是最推荐的方式。以 Maven 为例先在pom.xml里加上依赖我以 8.0.33 为例dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId version8.0.33/version /dependency如果你公司内部网络访问公网仓库慢或者拉取老失败可以在settings.xml里配置阿里云 Maven 镜像这样下载速度会快很多mirror idaliyunmaven/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirrorGradle 则这样写implementation com.mysql:mysql-connector-j:8.0.33依赖管理工具有个好处它会自动把依赖树理清楚避免手动拷贝 jar 造成的版本冲突。2.2 手动下载 Jar 包配置到本地有些老项目就是不爱用 Maven或者说部署环境是纯内网手工安装方式仍然有市场。你可以去 MySQL 官方网站的 Connector/J 下载页选择 Platform Independent 的 ZIP 包。解压之后目录里一般能看到mysql-connector-j-8.0.33.jarmysql-connector-j-8.0.33-source.zipdocs目录licenses目录如果你用的是 IntelliJ IDEA最简单的办法是把 jar 直接放到lib目录然后右键Add as Library。如果是 Eclipse则是 Build Path 里导入 External JARs。这里有个细节手动下载时建议连源码包一起下载排查问题的时候能直接看驱动内部实现尤其是调参数、查异常时源码能告诉你底层到底做了什么。2.3 离线环境安装到本地仓库内网部署常常遇到这种场景开发机能上网生产机完全隔离。这时候你可以在开发机上下载好 jar 包然后通过mvn install:install-file把 jar 安装到本地 Maven 仓库再打包部署。命令如下mvn install:install-file \ -Dfilemysql-connector-j-8.0.33.jar \ -DgroupIdcom.mysql \ -DartifactIdmysql-connector-j \ -Dversion8.0.33 \ -Dpackagingjar如果是公司内部私服还可以把 jar 上传到 Nexus 或 Artifactory让所有团队成员统一使用。这里我要多说一句内网环境里最容易犯的错是到生产服务器上随意复制一个 jar 放进去不去验证版本和兼容性。驱动 Jar 包不是“有就能跑”版本不对报错能让你查一晚上。2.4 版本选型建议市面上的驱动版本很多我整理了一个选型参考驱动版本建议适配场景是否推荐5.1.49老项目、MySQL 5.7 及以下不推荐新项目使用8.0.23可用但时区参数需要用serverTimezone看情况8.0.28兼容性较稳很多 Spring Boot 2.x 默认版本推荐8.0.338.0 系列较新的稳定版本修复不少 bug推荐如果你还没定版本我建议直接锁8.0.33或你团队验证过的某个 8.0.x 小版本。锁版本非常重要别用8.0.31这种又上线一阵子的版本裸奔也别用8.0.8这种远古版。稳定压倒一切。3. 驱动参数配置与核心原理3.1 JDBC URL 标准模板先用一段最常用的连接串jdbc:mysql://localhost:3306/order_db?useUnicodetruecharacterEncodingutf8zeroDateTimeBehaviorconvertToNulluseSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltruerewriteBatchedStatementstrueuseServerPrepStmtstrueuseAffectedRowstrue这段有点长我先解释几个必选参数然后给出一份可直接抄作业的安全配置。3.2 关键参数逐项拆解先说serverTimezone。MySQL 8.0 驱动连接时会拿服务器时区和 JVM 时区做对比如果拿到的时区是CST模棱两可它就会报错。最稳妥的做法是显式指定serverTimezoneAsia/Shanghai。如果你的数据库服务器本身设置了 UTC那你就要写UTC别照抄要看你服务器实际时区。然后是useSSL。MySQL 8.0 驱动对 SSL 的默认行为比以前严格如果你本地开发环境本身没有配置证书设置useSSLfalse可以省很多事。但从 8.0.13 开始官方更推荐用sslModeDISABLED替代useSSLfalse毕竟useSSL在后续版本被标记为过时。这里有个关键参数allowPublicKeyRetrievaltrue。这个参数很多人一开始不理解它的作用是在非 SSL 连接下当用户认证使用caching_sha2_password时客户端可以主动向服务端申请 RSA 公钥。简单说不开启就可能报Public Key Retrieval is not allowed但你真在公网上跑随便开这个参数也有中间人攻击风险。我个人的习惯是内网开发环境开启生产环境尽量用 SSL 或专用网络不要盲目复制。再来看字符集。useUnicodetruecharacterEncodingutf8是老默认配置但 MySQL 8.0 服务端本身已经默认utf8mb4所以单纯的utf8不一定够。建议连接里再增加connectionCollationutf8mb4_unicode_ci让连接层和库表排序规则保持一致。3.3 时区问题是最容易翻车的点时区这个事值得单独提。很多开发者本地在 Windows默认时区就是北京时间但测试服务器部署在境外或 Docker 容器里容器默认是 UTC。这时候你如果只在 URL 里写了serverTimezoneAsia/Shanghai而数据库服务器实际是SYSTEM并且系统时区是 UTC那查出来的数据可能和本地开发差 8 小时。MySQL 8.0 驱动从 8.0.23 开始支持connectionTimeZoneLOCAL原理是把数据库连接时区设置成 JVM 本地时区JVM 里捣腾时间戳会简单很多。我的建议如下单体应用直接设serverTimezoneAsia/Shanghai。有跨区域部署或容器化使用connectionTimeZoneLOCAL同时数据库JDBC URL里不要硬编码北京时间。还有一种更根治的办法在数据库初始化时直接统一默认时区SET GLOBAL time_zone 08:00;别小看这个配置实际项目中“时间差8小时”的工单很多不是后端逻辑问题而是这一层没对齐。3.4 DB连接池配置示例项目里基本不会拿着DriverManager直接写原生 JDBC而是接HikariCP或Druid。我用application.yml给一份 HikariCP 的参考配置spring: datasource: url: jdbc:mysql://localhost:3306/order_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue username: root password: changeMe driver-class-name: com.mysql.cj.jdbc.Driver hikari: minimum-idle: 5 maximum-pool-size: 20 pool-name: OrderDbHikariPool connection-timeout: 30000 idle-timeout: 600000 max-lifetime: 1800000 connection-test-query: SELECT 1如果是 Druid配置大概是spring: datasource: type: com.alibaba.druid.pool.DruidDataSource driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/order_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue druid: initial-size: 5 min-idle: 5 max-active: 20 test-while-idle: true validation-query: SELECT 1 filters: stat,wall,slf4j注意driver-class-name必须写新驱动类名这是我见过最多人忘记改的地方。3.5 关于autoReconnect的建议老资料里经常有人让你在 URL 上加autoReconnecttrue。说是数据库重启后连接能自动恢复。在 MySQL 8.0 官方驱动里autoReconnect默认是 false而且官方并不推荐把它当成万能药。更合理的方案是让连接池里的连接检测机制去处理失效连接比如 HikariCP 的max-lifetime和connection-test-query。你要是依赖老驱动的串行重连在高并发下反而容易造成连接风暴。4. 接入 Spring Boot 和其他框架的注意点4.1 Spring Boot 2.x 与 3.x 的默认差异不同 Spring Boot 版本默认管理的驱动依赖并不一样。Spring Boot 2.x 某些版本默认用mysql-connector-javaSpring Boot 3.x 开始几乎都切到了mysql-connector-j。如果你手动在pom.xml里面显式声明了依赖要注意和 Boot 默认版本是否冲突。我建议直接通过 Boot 的依赖管理来设置属性properties mysql.version8.0.33/mysql.version /properties这样 Boot 会自动帮你选对应坐标。如果你非得自己写 dependency最好带上scoperuntime/scope表示不需要在编译期直接依赖。4.2 MyBatis、JPA 等框架兼容性MyBatis 和 JPA 本身不直接依赖 JDBC 驱动的内部实现它们只依赖javax.sql.DataSource。所以只要连接池配置正确、驱动类名正确一般框架接入问题不大。这里最容易踩的坑是 MyBatis 分页插件或者 SQL 方言判断。如果你用PageHelper老版本可能识别不了 MySQL 8.0最好升级到较新版本。在 JPA 场景下Hibernate 方言需要显式设置spring.jpa.database-platformorg.hibernate.dialect.MySQL8Dialect服务端 MySQL 是 8.0但 Hibernate 方言写成了MySQL5Dialect虽然很多时候能跑但某些 SQL 生成行为和锁策略会不对味。对这种细节我的原则是能显式就不让框架猜测。4.3 普通 Java 项目里的手动加载不用 Spring 也不用任何框架纯 Java 项目用Class.forName(com.mysql.cj.jdbc.Driver)也能加载。但 8.0 驱动其实已经支持 ServiceLoader 机制JDBC 4.0 以后是自动注册驱动的你甚至不必写Class.forName。不过为了兼容老代码和某些老容器保留一行也没什么问题。真正要注意的是 classpath 里别同时存在两份驱动 jar——一份 5.x、一份 8.0.x这会造成加载时有概率拿到老版本驱动类然后各种怪异报错。5. 高频报错与排查思路5.1 错误速查表报错信息主要原因解决方向Public Key Retrieval is not allowed非 SSL 连接 caching_sha2_passwordURL 加allowPublicKeyRetrievaltrueClient does not support authentication protocol requested by server驱动版本过旧升级到 8.0.x 驱动The server time zone value CST is unrecognized未指定serverTimezone加serverTimezoneAsia/ShanghaiClassNotFoundException: com.mysql.jdbc.Driver驱动类名写旧改成com.mysql.cj.jdbc.DriverAccess denied for user rootlocalhost账号密码错误或远程登录限制检查授权用户和 hostCommunications link failure网络不通、防火墙、服务未启动检查端口连通性和数据库状态Unknown database数据库名不存在或大小写不一致确认库名5.2 排查一幕某电商项目启动就报 Public Key Retrieval我之前参与的一个电商订单系统 X开发的电脑上一切正常一部署到测试环境就报Caused by: java.sql.SQLException: Public Key Retrieval is not allowed我第一反应就是看 URL 是不是少了allowPublicKeyRetrievaltrue。结果发现测试环境的配置中心里确实没有这个参数因为那是从 MySQL 5.7 时代复制过来的老配置那时候用的还是mysql_native_password不需要公钥检索。后来我在配置中心统一加上了url: jdbc:mysql://db.internal:3306/order_db?useSSLfalseallowPublicKeyRetrievaltrueserverTimezoneAsia/Shanghai问题直接解决。这里的关键点是不是数据库密码错了也不是数据库连不上而是认证阶段的加签方式变了。遇到这类问题先看 URL再看驱动版本别一上来就改数据库用户。5.3 排查一幕连上了但时间差 8 小时还有一个印象特别深的排查经历。某后台管理系统的列表页里每条记录创建时间都比真实时间晚 8 个小时。最开始大家怀疑是 Java 把时间序列化错了调了 Jackson 配置也没用。后来我远程连上测试库执行SELECT NOW()发现数据库返回的时间本身是正常的。再看 JVM 配置发现 Docker 容器里/etc/localtime是 UTC然后连接串里没写serverTimezone。这种情况下驱动会把数据库的 UTC 时间按默认时区解释再转成 JVM 时区时又偏移一次。最终我把 URL 改成serverTimezoneAsia/Shanghai应用重新读取后时间就正常了。后来为了不再出这种幺蛾子我直接把数据库全局时区改成北京时间同时在 URL 里再显式指定一遍双保险。5.4 排查思路三步走如果你现在正被“连不上 MySQL 8.0”卡住别慌按这个顺序来先检查驱动版本是不是 8.0.x驱动类名是不是com.mysql.cj.jdbc.Driver。再检查 URL 里有没有serverTimezone如果是非 SSL 连接还需要allowPublicKeyRetrievaltrue。最后检查数据库账号的 host 限制和密码加密方式用SELECT user, host, plugin FROM mysql.user;看看远程连接的用户是不是被限定了 localhost。很多时候实际问题只集中在步骤 1 和 2。6. 性能与稳定性调优的经验6.1 连接池大小不是越大越好很多团队以为连接池开得多性能就越好。MySQL 8.0 默认最大连接数是 151你应用层开 200 个连接到时候挤压的是数据库本身。比较合理的估算方式是看业务请求量和单个请求占用连接的时间。公式可以这么理解连接池大小 ≈ 每秒请求数 × 单次请求数据库耗时秒如果你的系统每秒 500 个请求每个请求查库平均 20 毫秒那么理想连接池大约是500 × 0.02 10。当然这只是理论值还要算上网络抖动和慢 SQL 的余量。我一般把连接池的峰值设置成理论值的 3 到 5 倍但不会无限大。HikariCP 的maximum-pool-size20对于大多数中型应用足够。6.2 批量写入一定要开启 rewriteBatchedStatements执行 JDBC 批量插入的时候如果你没开rewriteBatchedStatementstrue驱动可能会把每条记录当成单独的 insert 一次一次发给数据库批量性能收益远远低于预期。MySQL 8.0 驱动里这个参数默认是 false我建议在数据初始化、迁移、批量导入场景下显式打开。配合useServerPrepStmtstrue和cachePrepStmtstrue服务端可以复用预编译语句减少 SQL 解析开销。我之前给某文件导入功能做过一次简单测试同样插入 5 万条数据开启前耗时一分钟左右开启后不到十秒。差别非常明显。6.3 连接泄漏和慢日志监控MySQL 8.0 驱动和连接池本身不会直接告诉你连接是不是泄漏了但你在连接池配置里可以埋一些监控。HikariCP 可以设置leak-detection-threshold只要连接被占用超过阈值日志里会提示可能泄漏。Druid 则可以通过 StatFilter 查看慢 SQLspring: datasource: druid: filter: stat: log-slow-sql: true slow-sql-millis: 1000线上环境尽量把慢 SQL 阈值设得小一点先发现问题再谈优化。6.4 配置统一管理避免各写各的这种细节我说过很多次一个项目的 MySQL JDBC URL 绝对不能在十几个服务里各写一套。比如 A 服务少了useAffectedRowstrueB 服务的更新返回行数语义就跟 A 不一样。我建议公共的 datasource 配置收敛到统一的配置中心或者公共依赖包URL 模板统一生成。另外连接串中的密码不要硬编码到 git 仓库优先使用环境变量、配置中心或者密钥管理工具。我见过好几次线上事故都是开发人员把生产数据库密码写在代码仓库里然后权限被扫描后拖库这个教训代价太大了。7. 版本升级落地自查清单如果你正好在规划从老驱动升级到 MySQL 8.0 JDBC 驱动我给你一份自查清单[ ] pom.xml 里的坐标已更新为com.mysql:mysql-connector-j[ ]driver-class-name已改为com.mysql.cj.jdbc.Driver[ ] URL 已加上serverTimezone[ ] URL 已按需加上useSSLfalse或sslModeDISABLED[ ] 非 SSL 内网环境已确认allowPublicKeyRetrievaltrue[ ] 批量写入场景已开启rewriteBatchedStatementstrue[ ] 连接池配置已确认没有使用老旧的autoReconnecttrue[ ] MyBatis 或 Hibernate 方言已指向 MySQL 8.0 版本[ ] classpath 里没有同时存在多个版本的 MySQL 驱动 jar我个人的做法是先把这些检查项做成脚本发布流水线里跑一遍发现问题直接拦截。别靠人肉巡检太容易漏。根据我自己的经验MySQL 8.0 的 JDBC 驱动升级技术难度不算高但坑位不少。本质上就是三件事驱动版本带对、URL 参数配置对、连接池行为理解对。只要这三件事做扎实大部分疑难杂症都能规避。如果你正在处理一个长期维护的老系统切记不要只改 jar 包版本要连带检查驱动类名、URL 参数和连接池版本否则你只是把一个坑换成了另一个坑。这版驱动后续的兼容方向还会继续朝着更严格的认证和加密走所以养成写完整参数的习惯比临时百度一个 URL 靠谱得多。