ThinkPHP8数据库连接被拒绝怎么办？_ThinkPHP8排查连接拒绝原因【运维】

说白了，Connection refused 不是 ThinkPHP 本身的问题，而是 PHP 试图建立 socket 连接时，被操作系统或数据库服务给拒绝了——这说明服务没有在监听，或者监听的地址端口跟配置对不上。

怎么看 PDOException 的真实错误信息

ThinkPHP 只是把底层的 PDO 异常原样抛了上来，所以关键线索全都藏在 PDOException::getMessage() 里。不同错误码对应着完全不同的问题场景：

• "SQLSTATE[HY000] [2002] Connection refused" → MySQL 进程压根没启动，或者配置里的 hostname 和 hostport 完全对不上
• "SQLSTATE[HY000] [1045] Access denied for user" → 用户权限不匹配。典型的坑是配置里写 127.0.0.1，但数据库里只建了 'user'@'localhost'，两者在 MySQL 的权限体系里是两套记录
• "SQLSTATE[HY000] [2002] No such file or directory" → 配置用了 localhost 但 Unix socket 没启用，或者 socket 路径不对。比如 Mac M1 Homebrew 的默认路径是 /opt/homebrew/var/mysql/mysql.sock

别停留在“数据库连接失败”这个笼统的表述上。去 runtime/log/ 找最新日志，把整条带 PDOException 的 message 复制出来，这才是诊断的依据。

为什么 host 和 port 看似写对了还是 Connection refused

很多问题不是拼写错误，而是网络语义和类型隐式转换搞的鬼：

• hostname 尽量别写 localhost：在多数系统下它会强制走 Unix socket，而你配的 hostport 是给 TCP 用的，两套机制互不兼容。测试时统一用 127.0.0.1
• hostport 必须是整数：如果写成 '3306'（字符串），ThinkPHP 8 传给 PDO 时会 fallback 到默认端口（比如 0），实际连到了完全不同的地方
• Docker 环境里，hostname 不能写 127.0.0.1 或 localhost，得用容器名（如 mysql）或宿主机网关（如 host.docker.internal）
• 云服务器上，MySQL 用户的 host 字段必须是 '%' 或具体公网 IP，要是配了 'localhost'，远程请求自然被直接拒绝

env 文件覆盖配置没生效？快速验证一下

.env 不是写了就能生效，有三个硬性前提：

• .env 文件必须放在项目根目录（和 think 命令同级），放在 config/ 或 app/ 下面读不到
• APP_DEBUG 必须为 true，否则环境变量加载逻辑会被跳过——这是最容易忽略的一点
• 键名必须全大写加下划线：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。这事跟 ThinkPHP 无关，是 PHP 7.4 以下版本的 PDO 不认识 MySQL 8.0 默认的认证插件。

• 登录 MySQL 命令行，执行：ALTER USER 'your_user'@'%' IDENTIFIED WITH mysql_native_password BY 'your_password';
• 注意 @'%' 要跟你 PHP 实际连接来源一致。比如如果是 Docker 容器，就要改成 @'172.x.x.x' 或 @'%'
• 执行 FLUSH PRIVILEGES; 让改动生效
• 确认 phpinfo() 里启用了 pdo_mysql 扩展，且 PHP 版本 ≥ 7.2

这里有个坑：同一个用户名在不同 host 下可能绑定了不同的认证插件。所以一定要先查清楚实际匹配的是哪一条记录——用 SELECT user, host, plugin FROM mysql.user 确认。