ThinkPHP5数据库连接失败怎么办？_ThinkPHP5解决连接异常问题【维护】

排查数据库连接这类坑，最怕的就是方向错——上来就改配置、重启服务，结果问题根本没找对。其实，直接从 PDOException 的 message 字段入手，90% 的根因一眼就能看穿，根本不需要绕弯路。

直接看 PDOException 的 message 字段，90% 的连接失败靠它就能准确定位，而不是一上来就改配置或重启服务。

怎么看 PDOException 的真实错误信息

ThinkPHP 5 不自己抛连接层异常，它只是把 PDO 抛出的原始错误原样往上扔。关键线索全在 message 里：

• "SQLSTATE[HY000] [2002] Connection refused" → MySQL 进程没启动，或 hostname 和 hostport 配得不对（比如填了 localhost 却没开 socket，或端口被防火墙拦了）
• "SQLSTATE[HY000] [1045] Access denied for user" → 用户名、密码、host 三者至少一个不匹配；常见于云服务器上用户是 'user'@'localhost'，但 PHP 是从外网连的
• "SQLSTATE[HY000] [2002] No such file or directory" → hostname 写了 localhost，但 MySQL 没监听 Unix socket，或路径和 ThinkPHP 期望的不一致（Mac M1 Homebrew 安装默认只建 socket 文件）

别只扫一眼日志里的“数据库连接失败”，去 runtime/log/ 下翻最新日志，找到带完整 PDOException 堆栈的那一行，复制整段 message 再判断。

hostname 和 hostport 看似写对了，为什么还是连不上

问题常出在语义错位，不是语法错：

• hostname 别写 localhost：它在 Linux/macOS 下默认走 Unix socket，而你配的 hostport 是给 TCP 用的，两者根本不在一个通道上。统一用 127.0.0.1 测试
• hostport 必须是整数：写成 '3306'（字符串）会导致 TP5.1+ 传给 PDO 时类型不匹配，PDO 会静默 fallback 到默认端口 3306，但某些环境会直接失败
• Docker 环境中，hostname 不能写 127.0.0.1 或 localhost，得换成容器名（如 mysql）或宿主机网关（如 host.docker.internal）
• 云服务器（阿里云/腾讯云）上，MySQL 用户的 host 字段必须是 '%' 或具体公网 IP，不能是 'localhost'——远程请求进来第一关就被拒

.env 文件没生效？先验三个硬条件

TP5 默认不读 .env，它只在满足全部以下条件时才加载：

• .env 文件必须放在项目根目录（和 think 命令同级），不是 app/ 或 config/ 下
• APP_DEBUG 必须为 true，否则整个环境变量加载逻辑会被跳过（这是最常被忽略的一点）
• .env 里键名必须全大写加下划线，例如 DB_HOST=127.0.0.1，写成 db_host 或 Db_Host 都读不到

验证是否加载成功，控制器里临时加一句：dump(env('DB_HOST'));。输出 null 就说明上面三点至少有一条没做到。

MySQL 8.0+ 报 caching_sha2_password 错误怎么修

错误信息类似：Authentication plugin 'caching_sha2_password' cannot be loaded。这不是 TP5 的问题，是 PHP 7.4 以下版本的 PDO 扩展不支持 MySQL 8.0 默认认证方式。

• 不要降级 MySQL，也不要用 mysql_native_password 全局改配置（影响其他服务）
• 只改对应用户：登录 MySQL（本地），执行：ALTER USER 'your_user'@'%' IDENTIFIED WITH mysql_native_password BY 'your_password';
• 如果用户是限定 IP 的（如 'tp_app'@'192.168.1.100'），就把 '%' 换成那个 IP
• 执行完记得 FLUSH PRIVILEGES;

真正麻烦的不是报错本身，而是很多人卡在“以为改了配置就完了”，却没意识到 PDOException::getMessage() 才是唯一可信信源，所有排查动作都该围绕它展开。