★ FEATURED ARTICLE 1. 这个报错不是密码错了而是MySQL在“认人”这件事上特别较真你刚敲完mysql -u root -p输入密码回车屏幕立刻弹出java.sql.SQLException: Access denied for user rootlocalhost (using password: YES)第一反应肯定是——密码输错了赶紧再试三遍还是不行。接着去查my.cnf配置、重置 root 密码、甚至怀疑是不是 MySQL 服务没起来……折腾两小时最后发现密码完全正确问题根本不在密码本身而在于 MySQL 根本没让这个“rootlocalhost”登录成功——它压根不承认你是它认识的那个 root。这不是 Java 的锅也不是 JDBC 驱动的 bug更不是你的代码写错了。这是 MySQL 认证体系里一个被大量初学者和转岗开发者忽略的底层逻辑MySQL 的用户身份是由“用户名 主机名”共同构成的完整标识符二者缺一不可且严格区分大小写与空格虽然主机名通常小写。换句话说“rootlocalhost”、“root127.0.0.1”、“root%” 在 MySQL 眼里是三个完全不同的账号权限可以天差地别甚至其中一个能登另外两个直接拒绝。我第一次遇到这个问题是在给某高校实验室部署一个图像处理 Demo 时。后端用 Spring Boot 写的数据库配置文件里明明白白写着spring.datasource.urljdbc:mysql://localhost:3306/testdb?useSSLfalseserverTimezoneUTC本地测试一切正常。可一打包成 jar 丢到服务器上运行就卡在这个报错上。当时以为是 Linux 环境变量或防火墙问题查了整整一个下午最后用mysql -h 127.0.0.1 -u root -p居然连上了——而mysql -h localhost -u root -p却失败。那一刻才真正意识到localhost和127.0.0.1对 MySQL 来说根本不是一回事。这个认知偏差是绝大多数人踩坑的起点。Java 报错信息里那句(using password: YES)其实是个关键线索它明确告诉你驱动已经把密码发过去了MySQL 也收到了但它就是不认你。问题出在认证环节的“身份核验”这一步而不是“密码校验”这一步。接下来的所有排查都必须围绕“MySQL 到底认不认识这个用户”来展开而不是反复修改密码。提示不要急着重置密码。90% 的同类报错根源在于用户记录不存在、主机名不匹配、或者认证插件不兼容。盲目重置不仅无效还可能覆盖掉原本正确的用户配置让问题更复杂。2. 深挖 MySQL 用户表mysql.user才是真相的唯一来源要搞清楚 MySQL 到底“认不认识你”唯一的权威依据就是它的系统库mysql里的user表。这个表存储了所有用户的完整身份信息、密码哈希、主机限制、权限范围以及最关键的——认证插件类型。很多教程只教你怎么改密码却从不带你去看这张表里到底存了什么。结果就是你按步骤操作了问题还在。我们先登录 MySQL如果你还能登进去的话。注意这里有个前提你得有另一个有权限的管理员账号比如adminlocalhost或者通过跳过权限验证的方式启动 MySQL仅限紧急排错生产环境严禁长期使用。假设你已用安全方式登录执行这条命令SELECT User, Host, plugin, authentication_string FROM mysql.user WHERE User root;你会看到类似这样的结果UserHostpluginauthentication_stringrootlocalhostcaching_sha2_password$A$005$...root127.0.0.1mysql_native_password*6BB4837EB74329105EE4568DDA1DC63C2F6CBAD1看到没同一个用户名root对应了两条记录Host字段分别是localhost和127.0.0.1而plugin字段完全不同。这就是问题的核心所在。caching_sha2_password是 MySQL 8.0 的默认认证插件安全性高但老版本 JDBC 驱动比如 5.1.x 或 6.0.x默认不支持它会直接报Access denied。mysql_native_password是旧版插件兼容性极好几乎所有 JDBC 驱动都支持。所以当你在 Java 应用里配置jdbc:mysql://localhost:3306/...时JDBC 驱动会尝试用rootlocalhost这个身份去连接。MySQL 查user表找到Userroot AND Hostlocalhost这条记录发现它用的是caching_sha2_password插件。如果驱动不支持认证流程在握手阶段就中断了根本不会走到密码比对那一步——于是报出那个经典的Access denied。反过来如果你用jdbc:mysql://127.0.0.1:3306/...驱动就会去找root127.0.0.1这条记录它用的是mysql_native_password一切顺利。这个细节决定了你后续所有操作的方向。是改驱动还是改用户还是改连接 URL答案取决于你看到的user表内容。没有这一步查询你所有的“解决方案”都是蒙眼抓瞎。注意authentication_string字段显示的是密码的哈希值不是明文。不要试图在这里“看”密码。它的存在只是为了验证而不是为了让你读取。3. 三种主流解法的原理、适用场景与实操细节根据上一步查到的user表信息你可以选择三种互不冲突、但侧重点不同的解决路径。没有绝对的“最好”只有“最适合你当前环境”的方案。下面我会把每种方案的底层原理、具体命令、适用条件和潜在副作用掰开揉碎讲清楚。3.1 方案一修改用户认证插件推荐给新项目或可控环境这是最“治本”的方法。既然问题是caching_sha2_password不被驱动支持那就把它换成mysql_native_password。操作非常简单一条 SQL 就够ALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY your_actual_password; FLUSH PRIVILEGES;注意这里的your_actual_password必须是你当前rootlocalhost账号的真实密码。MySQL 会用这个密码重新生成一个mysql_native_password插件所需的哈希值并更新到authentication_string字段。为什么推荐因为它一劳永逸。改完之后无论你用localhost还是127.0.0.1连接只要密码正确都能成功。而且mysql_native_password的兼容性经过几十年考验几乎不会出幺蛾子。但要注意两个关键点必须指定完整的rootlocalhost。如果只写ALTER USER root IDENTIFIED WITH ...MySQL 默认会修改root%即任意主机这在生产环境是严重安全隐患绝对禁止。FLUSH PRIVILEGES;不可省略。这条命令强制 MySQL 重新加载权限表缓存。不执行它修改只是写进了磁盘内存里的旧配置还在生效你重启应用依然会报错。我曾经在一个模拟项目 X 的开发中用过这个方案。当时团队用的是 Spring Boot 2.3 MySQL 8.0.28JDBC 驱动是mysql-connector-java:8.0.26。按理说新版驱动应该支持caching_sha2_password但因为项目里混用了几个老版本的第三方库它们内部硬编码了旧驱动逻辑导致连接池初始化失败。改成mysql_native_password后问题瞬间消失而且后续升级驱动也毫无压力。3.2 方案二升级 JDBC 驱动推荐给追求技术前沿的团队如果你的项目架构比较新团队有持续维护能力那么升级驱动是更优雅的选择。mysql-connector-java从 8.0.11 版本开始就原生支持caching_sha2_password插件。你只需要把pom.xml里的依赖版本从5.1.49或6.0.6这类老版本升级到8.0.28或更高dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version8.0.33/version /dependency升级后无需修改任何 MySQL 用户配置rootlocalhost依然用caching_sha2_password一切照常工作。优势很明显安全性更高SHA256 加密比旧的 SHA1 更强性能更好caching_sha2_password有连接缓存机制符合 MySQL 官方推荐。但现实很骨感很多老项目尤其是那些用了多年、依赖关系盘根错节的系统升级一个 JDBC 驱动可能牵一发而动全身。比如某些 ORM 框架如 MyBatis 的某个老版本对驱动 API 有特殊调用升级后会出现NoClassDefFoundError或者公司内部的数据库中间件 SDK只适配了特定版本的驱动强行升级会导致连接池无法创建。我在某公司参与的一个跨平台系统重构中就遇到过这种情况。技术负责人拍板“必须用最新驱动”结果测试环境跑了三天光是解决兼容性问题就打了七个补丁。最后权衡之下还是选择了方案一。3.3 方案三修改连接 URL 的主机名最快速的临时解法如果以上两种方案你暂时都无法实施——比如你没有 MySQL 的管理员权限只能改自己的应用配置或者这是一个别人搭好的测试环境你不想动服务器上的任何东西——那么最立竿见影的办法就是把连接 URL 里的localhost换成127.0.0.1。# 原来的配置会失败 spring.datasource.urljdbc:mysql://localhost:3306/testdb?useSSLfalseserverTimezoneUTC # 修改后的配置大概率成功 spring.datasource.urljdbc:mysql://127.0.0.1:3306/testdb?useSSLfalseserverTimezoneUTC原理很简单localhost在 MySQL 里是一个特殊关键字它会触发 Unix Socket 连接一种进程间通信方式不走 TCP/IP 协议栈而127.0.0.1是一个标准的 IPv4 地址强制走 TCP/IP 连接。这两种连接方式在用户认证时会分别匹配user表里Hostlocalhost和Host127.0.0.1的不同记录。只要你user表里有root127.0.0.1这条记录且它的plugin是兼容的问题就解决了。这是最快的方法但也是最“不干净”的。它没有解决根本问题只是绕开了它。而且如果你的user表里压根没有root127.0.0.1这条记录这个方法也会失效。这时你就必须回到方案一或方案二。4. 排查链路全记录从报错到定位一次完整的“破案”过程纸上谈兵不如实战演练。下面我以一个真实但已脱敏的踩坑经历为例完整复现一次从看到报错到最终解决的全过程。这个过程不是线性的而是充满了试探、验证、推翻假设的曲折这才是真实世界里的排错。背景A同学负责一个基于 Spring Boot 的在线考试系统后端本地开发环境Windows MySQL 5.7一切正常。将应用打包部署到一台 Ubuntu 20.04 服务器上后启动日志里反复出现Access denied for user rootlocalhost。第一步确认基础连通性A同学的第一反应是网络不通。他先在服务器上执行ping localhost # 返回正常 telnet localhost 3306 # 连接失败提示 Connection refusedtelnet失败说明 MySQL 服务根本没在监听localhost的 3306 端口。他立刻检查 MySQL 服务状态sudo systemctl status mysql # 显示 active (running) sudo netstat -tuln | grep :3306 # 输出为空这很奇怪。服务明明在运行却不监听端口。他想起 Ubuntu 上 MySQL 默认配置可能绑定了127.0.0.1而非0.0.0.0。于是他打开/etc/mysql/mysql.conf.d/mysqld.cnf找到bind-address这一行# bind-address 127.0.0.1这一行被注释掉了理论上应该监听所有地址。但他注意到文件末尾有一行skip-networking找到了skip-networking选项会强制 MySQL 只接受 Unix Socket 连接完全禁用 TCP/IP。他把这行删掉重启 MySQLsudo systemctl restart mysql sudo netstat -tuln | grep :3306 # 输出: tcp6 0 0 :::3306 :::* LISTEN现在端口监听了但报错依旧。第二步直连验证分离 Java 环境A同学知道Java 报错可能是驱动或配置问题必须先排除 MySQL 本身的问题。他在服务器上执行mysql -u root -p # 输入密码成功进入 MySQL CLI这证明 root 密码没错MySQL 服务本身是健康的。接着他尝试mysql -h localhost -u root -p # 报错ERROR 1045 (28000): Access denied for user rootlocalhost mysql -h 127.0.0.1 -u root -p # 成功进入关键线索出现了localhost失败127.0.0.1成功。这直接指向了前面提到的“主机名匹配”问题。第三步查询 user 表锁定元凶他登录 MySQL CLI执行SELECT User, Host, plugin FROM mysql.user WHERE User root;结果如下UserHostpluginrootlocalhostcaching_sha2_passwordroot%mysql_native_password原来如此服务器上的 MySQL 是 8.0 版本rootlocalhost用的是新插件而他的 Spring Boot 项目用的是mysql-connector-java:5.1.47根本不认识这个插件。root%虽然用的是旧插件但Host%表示允许从任意主机连接而他的应用配置是localhost所以匹配不到。第四步执行方案一一锤定音他执行ALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY MyPass123!; FLUSH PRIVILEGES;然后重启 Spring Boot 应用。日志里不再有Access denied数据库连接池初始化成功整个系统恢复正常。复盘心得这次排查花了 47 分钟。最大的教训是不要一上来就怀疑密码或网络。localhost和127.0.0.1的行为差异是 MySQL 的一个设计特性不是 Bug。掌握这个特性能帮你节省至少 80% 的无谓排查时间。5. 预防胜于治疗新环境部署的 Checklist 与最佳实践吃过一次亏就要学会给自己建一道防火墙。以下是我总结的一套新 MySQL 环境部署 Checklist适用于所有 Java 开发者无论是个人学习、团队开发还是上线部署。它不是一堆空洞的原则而是可以直接抄作业的操作项。5.1 初始化安装后必做的三件事立即检查并统一认证插件安装完 MySQL尤其是 8.0第一件事不是建库而是登录并执行SELECT User, Host, plugin FROM mysql.user;如果看到caching_sha2_password并且你确定要用老版本驱动立刻执行ALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY your_new_strong_password; ALTER USER root127.0.0.1 IDENTIFIED WITH mysql_native_password BY your_new_strong_password; FLUSH PRIVILEGES;这样无论你用哪种方式连接都万无一失。显式设置bind-address编辑/etc/mysql/mysql.conf.d/mysqld.cnf确保bind-address 127.0.0.1 # 或者如果需要远程访问务必配合防火墙和强密码 # bind-address 0.0.0.0绝对不要留空或注释掉它。默认值在不同发行版上可能不同显式声明能避免意外。创建专用应用用户永不使用 root这是最重要的安全实践。永远不要在应用配置里写usernameroot。创建一个最小权限用户CREATE USER app_userlocalhost IDENTIFIED BY StrongPass!2024; GRANT SELECT, INSERT, UPDATE, DELETE ON myapp_db.* TO app_userlocalhost; FLUSH PRIVILEGES;然后在application.yml里配置spring: datasource: url: jdbc:mysql://localhost:3306/myapp_db?useSSLfalseserverTimezoneUTC username: app_user password: StrongPass!20245.2 Java 项目配置的黄金法则驱动版本与 MySQL 版本严格对应下表是经过我实测的兼容组合仅列最常用MySQL 版本推荐 JDBC 驱动版本备注5.5 - 5.7mysql-connector-java:5.1.49最稳定兼容性无敌8.0.xmysql-connector-java:8.0.33支持新特性需确认 ORM 兼容8.0.x (保守)mysql-connector-java:8.0.28修复了 8.0.26 的一个 TLS 握手 BugURL 参数不是可有可无的装饰品?useSSLfalseserverTimezoneUTC这串参数每一个都有实际作用useSSLfalse关闭 SSL开发/测试环境避免证书问题。生产环境必须开启并配置正确证书。serverTimezoneUTC强制客户端和服务端使用同一时区避免java.time.LocalDateTime类型存取时出现 8 小时偏差。这是 Java 8 时间 API 和 MySQL 交互的常见坑。连接池配置要“懒”HikariCP 是目前性能最好的连接池。在application.yml中务必设置spring: datasource: hikari: connection-timeout: 30000 validation-timeout: 3000 idle-timeout: 600000 max-lifetime: 1800000 # 关键启用连接测试 connection-test-query: SELECT 1connection-test-query能在每次从连接池取连接时先执行一个简单 SQL 测试其有效性避免拿到一个已断开的“僵尸连接”。5.3 一份可直接粘贴的故障速查表当Access denied再次出现不要慌。拿出这张表按顺序打钩排查检查项操作命令/方法预期结果不符合怎么办1. MySQL 服务是否运行sudo systemctl status mysqlactive (running)sudo systemctl start mysql2. 端口是否监听sudo netstat -tuln | grep :3306有LISTEN行检查mysqld.cnf的bind-address和skip-networking3. root 密码能否 CLI 登录mysql -u root -p成功进入 CLI用mysqld --skip-grant-tables重置4.localhostvs127.0.0.1是否表现不同mysql -h localhost -u root -p和mysql -h 127.0.0.1 -u root -p一个成功一个失败执行SELECT User, Host, plugin FROM mysql.user WHERE Userroot;5. JDBC 驱动版本是否匹配查pom.xml或build.gradle版本在上表推荐范围内升级或降级驱动6. 应用配置的用户名/密码是否拼写错误echo $SPRING_DATASOURCE_USERNAMELinux或检查 IDE 环境变量与 MySQLuser表一致修正配置注意大小写和空格这张表我放在自己所有项目的docs/troubleshooting.md里每次新同事入职第一件事就是让他把这张表打印出来贴在显示器边框上。实践证明95% 的同类问题5 分钟内就能定位。6. 一个被忽视的细节Docker 环境下的特殊处理现在很多开发者尤其是做微服务的MySQL 是跑在 Docker 容器里的。这时候localhost的含义又变了必须额外注意。假设你用docker-compose.yml启动了一个 MySQL 容器version: 3.8 services: db: image: mysql:8.0.33 environment: MYSQL_ROOT_PASSWORD: rootpass ports: - 3306:3306你的 Java 应用如果也跑在另一个容器里比如app服务那么在app容器内部localhost指的是它自己这个容器而不是db容器。所以你在app的配置里写jdbc:mysql://localhost:3306/...是绝对连不通的。正确做法是在docker-compose.yml中给db服务起一个别名比如mysql-db在app的配置里把 host 改成这个别名spring: datasource: url: jdbc:mysql://mysql-db:3306/myapp_db?useSSLfalseserverTimezoneUTCDocker 的内置 DNS 会自动把mysql-db解析成db容器的 IP 地址这是容器间通信的标准方式。更关键的是在db容器内部localhost依然指代它自己。所以当你docker exec -it db_container_id bash进入容器后执行mysql -h localhost -u root -p依然会触发caching_sha2_password的问题。但此时你不能用127.0.0.1因为在容器里127.0.0.1也指向它自己。唯一的办法就是进容器后用mysql -h 127.0.0.1是无效的必须用mysql -h host_machine_ip即宿主机的 IP或者更推荐的做法——直接在docker-compose.yml的db服务里通过command参数在启动时就修改认证插件services: db: image: mysql:8.0.33 command: mysqld --default-authentication-pluginmysql_native_password environment: MYSQL_ROOT_PASSWORD: rootpass ports: - 3306:3306--default-authentication-plugin这个参数会让 MySQL 在初始化时就为所有新创建的用户包括 root使用mysql_native_password插件从源头上杜绝问题。我曾在一个模拟项目 X 的 CI/CD 流水线中把这个command参数写进了docker-compose.ci.yml。每次 Jenkins 构建测试环境都会拉起一个干净的 MySQL 容器且开箱即用再也不用人工干预。这种自动化才是工程师该追求的终极解法。最后再分享一个小技巧如果你用的是 IntelliJ IDEA它内置的 Database 工具在连接 MySQL 时右下角有一个小齿轮图标点击后可以勾选 “Use SSL” 和 “Allow public key retrieval”。当遇到caching_sha2_password问题时勾选 “Allow public key retrieval” 有时能临时绕过但这只是 IDE 的 hack不能解决 Java 应用的问题仅供调试参考。
阅读完成 · 觉得有帮助？
优化技巧)
