前言网站突然白屏或者返回 500日志里只有一行没头没尾的报错比如SQLSTATE[HY000] [2002] No such file or directory、Fatal error: Uncaught mysqli_sql_exception: Connection refused或者干脆什么都没有——页面空白、日志干净。数据库连接失败最难受的地方就在这里症状在 PHP 这一侧原因往往在 PHP 之外可能在账号权限、可能在认证插件、可能在容器的网络命名空间。更麻烦的是PHP 8.0 之后连接错误的表达方式变了。以前失败的连接函数返回false代码里if (!$link) { die(连接失败); }能兜住现在很多路径直接抛异常兜不住就是致命错误。排查手段如果没有跟着升级就会出现报错信息反而变少了的错觉。本文按分层定位的思路梳理先弄清一次连接要穿过哪几道门、每道门失败时是什么报错再给出一份可以直接跑的诊断脚本最后拆开 MySQL 8 认证插件、localhost与 socket 这两类最高频的成因。文中的示例代码需要 PHP 8.0 及以上使用的都是你环境里已有的原生 API。一、把错误分层一次连接要穿过哪几道门不要一上来就改代码。把连接过程拆成五层报错信息基本能自动定位到层层检查对象典型报错判断依据1. 扩展层pdo_mysql/mysqli是否加载could not find driver、Call to undefined function mysqli_connect()报错里根本没有 MySQL 错误码2. 解析层DSN / 参数拼写invalid data source name错误发生在连接之前3. 网络层host、port、socket 路径[2002] Connection refused、No such file or directory错误码以 2002 开头4. 认证层用户名、密码、授权主机、认证插件[1045] Access denied、authentication method unknown to the client错误码 1045 或插件名5. 库/权限层库是否存在、账号是否有权限[1049] Unknown database、[1044]连接已建立但选择库失败区分第 3 层和第 4 层尤其重要2002说明 TCP 或 socket 根本没通改密码是白改1045说明网络通了是凭据或授权主机的问题。二、想清楚为什么错误信息不见了PHP 8.0 起有一批行为变化它们本身是对的但会让老代码的容错逻辑失效PDO 在连接失败时总会抛PDOException无论PDO::ATTR_ERRMODE设成什么官方手册对此有明确说明。也就是说把ERRMODE设成SILENT并不能让new PDO(...)静默失败而未被捕获的异常是致命错误。老代码里$pdo new PDO(...); if (!$pdo) {...}这种写法从来不成立。mysqli 从 PHP 8.1 起默认MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT连接失败会抛mysqli_sql_exception而不是像以前那样返回false并给一个 warning。依赖mysqli_connect()返回false的旧代码会因为抛异常而中断。需要旧行为时可以显式调用mysqli_report(MYSQLI_REPORT_OFF);但更推荐改成try/catch。PHP 8.1 起 DSN 解析更严格把host错写成hostname这类拼写错误以前会被静默忽略并退回默认值现在会直接抛PDOException。这其实是好事——错误提前暴露了。所以第一步是让错误可见打开display_errors仅限开发环境、把error_reporting设为E_ALL、并确保异常不被一个空的catch (Exception $e) {}吃掉。三、一份可运行的分层诊断脚本把下面这个脚本放到线上环境跑一次注意先确认能承受它暴露的信息用完删除它会按顺序检查扩展、PHP 配置、网络端口、认证情况并把每一层的结论打印出来?php // db_check.php —— 需要 PHP 8.0 及以上 declare(strict_types1); $host getenv(DB_HOST) ?: 127.0.0.1; $port (int) (getenv(DB_PORT) ?: 3306); $user getenv(DB_USER) ?: app; $pass getenv(DB_PASS) ?: secret; $dbname getenv(DB_NAME) ?: app; echo PHP 版本: , PHP_VERSION, PHP_EOL; echo SAPI: , PHP_SAPI, PHP_EOL, PHP_EOL; // ---- 第 1 层扩展 ---- foreach ([pdo_mysql, mysqli, mysqlnd] as $ext) { printf(扩展 %-10s : %s\n, $ext, extension_loaded($ext) ? 已加载 : 未加载); } echo PHP_EOL; // ---- 第 2 层网络 ---- $errno 0; $errstr ; $fp fsockopen($host, $port, $errno, $errstr, 3.0); if ($fp false) { echo [网络层] 无法连接 {$host}:{$port} —— errno{$errno} {$errstr}, PHP_EOL; echo 如果是容器环境请确认 host 用的是服务名而不是 127.0.0.1。, PHP_EOL; } else { echo [网络层] TCP 可达 {$host}:{$port}, PHP_EOL; fclose($fp); } echo PHP_EOL; // ---- 第 3~5 层PDO 实测 ---- $dsn sprintf(mysql:host%s;port%d;dbname%s;charsetutf8mb4, $host, $port, $dbname); try { $pdo new PDO($dsn, $user, $pass, [ PDO::ATTR_ERRMODE PDO::ERRMODE_EXCEPTION, PDO::ATTR_DEFAULT_FETCH_MODE PDO::FETCH_ASSOC, PDO::ATTR_TIMEOUT 3, ]); $row $pdo-query(SELECT VERSION() AS v)-fetch(); echo [连接层] 成功服务端版本: , $row[v], PHP_EOL; $row $pdo-query(SHOW VARIABLES LIKE character_set_connection)-fetch(); echo [连接层] 连接字符集: , $row[Value], PHP_EOL; $row $pdo-query(SELECT CURRENT_USER() AS u)-fetch(); echo [认证层] 实际生效账号: , $row[u], PHP_EOL; } catch (PDOException $e) { // 注意连接失败时 PDO 一定会抛异常这里必须捕获 echo [PDO 错误] , $e-getMessage(), PHP_EOL; if (isset($e-errorInfo[1])) { echo 错误码: , $e-errorInfo[1], PHP_EOL; } echo 排查提示: , match (true) { str_contains($e-getMessage(), 1045) 凭据或授权主机不匹配检查 用户名主机 组合, str_contains($e-getMessage(), 1049) 库不存在确认 dbname 与 CREATE DATABASE, str_contains($e-getMessage(), 2002) TCP/socket 不通优先确认 host 与端口, str_contains($e-getMessage(), caching_sha2_password) 客户端库不支持新认证插件见第四节, default 请对照第一节的错误分层表定位, }, PHP_EOL; }再补一条命令确认 PHP 到底读的是哪个配置文件——我明明改了 php.ini这类问题九成出在这里php --ini # 查看加载的 php.ini 路径 php -m | grep -i mysql # 确认 pdo_mysql / mysqli 在不在列表里 php -r var_dump(PDO::getAvailableDrivers());四、两个最高频成因认证插件与 socket成因一MySQL 8 的caching_sha2_password。MySQL 8.0 起默认认证插件从mysql_native_password换成了caching_sha2_password。如果 PHP 侧链接的是较老的客户端库或者在容器里换过基础镜像导致mysqlnd版本不一致就会报The server requested authentication method unknown to the client或caching_sha2_password cannot be loaded。处理方向有两个建议优先第一个-- 方向 A推荐让客户端支持新插件 —— 升级 PHP / mysqlnd或启用 TLS 连接 -- 方向 B临时把账号降级到老插件该插件已被标记过时MySQL 9 已移除仅作过渡 ALTER USER app% IDENTIFIED WITH mysql_native_password BY 你的密码; FLUSH PRIVILEGES; -- 顺带确认账号的授权主机1045 很多时候是这里不匹配 SELECT user, host, plugin FROM mysql.user WHERE user app;排查这类问题时有个很好的对照手段用命令行客户端以同一账号连一次。如果mysql -h 127.0.0.1 -u app -p能进说明服务端、账号、插件、授权都没问题问题就落在 PHP 侧的客户端库或 DSN 上反之则不必再折腾 PHP。成因二localhost与 socket 的歧义。在 MySQL 的约定里hostlocalhost不是用 TCP 连本机而是用 Unix socket 连本机。PDO/mysqli 会去找编译期或php.ini里配置的 socket 路径常见如pdo_mysql.default_socket、mysqli.default_socket。如果 MySQL 实际的 socket 在/var/run/mysqld/mysqld.sock而 PHP 的默认值指向别处就会得到[2002] No such file or directory——看起来像数据库没启动其实数据库好得很。; php.ini —— 显式指定 socket 路径或干脆统一改用 127.0.0.1 走 TCP pdo_mysql.default_socket /var/run/mysqld/mysqld.sock mysqli.default_socket /var/run/mysqld/mysqld.sock?php // 也可以在 DSN 里显式指定二者取其一 $pdo new PDO(mysql:unix_socket/var/run/mysqld/mysqld.sock;dbnameapp;charsetutf8mb4, $user, $pass); // 或者明确走 TCPhost 写 127.0.0.1 而不是 localhost $pdo new PDO(mysql:host127.0.0.1;port3306;dbnameapp;charsetutf8mb4, $user, $pass);常见坑点❌ 抓到一个catch (Exception $e) {}空块或者用把连接错误吞掉✅ 连接失败要显式捕获并记录catch (PDOException $e) { error_log($e-getMessage()); }注意PDOException继承自RuntimeException别只 catchException之外的父类❌ 容器里 DSN 还写着host127.0.0.1然后抱怨连不上✅ 容器内的127.0.0.1是容器自己应当用 Compose/K8s 里的服务名如db作为 host并确认在同一个网络里❌ 看到2002就去重置数据库密码✅2002是网络/socket 层问题先查 mysqld 是否监听、bind-address、防火墙与安全组再谈凭据❌ 只在php.ini里加了 socket 路径却忘了 PHP 读的是另一个php.ini✅ 先php --ini确认加载路径CLI 与php-fpm可能读不同的文件改完记得重启php-fpm/ 容器进程❌ 用hostlocalhost在 Linux 上得到2002就断定数据库没起来✅ 改用127.0.0.1或显式unix_socket再验证一次这一步能立刻把 socket 路径问题从网络问题里摘出来❌ 把[1045] Access denied当成密码错反复改密码✅ 报错里的app172.17.0.5才是关键——授权主机不匹配才是常见原因按来源网段补GRANT ... TO app172.17.%❌GRANT ALL ON *.* TO app%一把梭出问题时无法收敛权限✅ 只授业务库权限并限定来源主机排查时反而更容易看出是权限还是网络问题❌ 在 PHP 8.1 及以上沿用mysqli_connect()返回false的判断不包try/catch✅ 8.1 起 mysqli 默认抛mysqli_sql_exception要么改try/catch要么显式mysqli_report(MYSQLI_REPORT_OFF);回到旧行为总结现象/错误码所在层优先动作could not find driver扩展层安装并启用pdo_mysqlphp --ini确认配置文件invalid data source name解析层检查 DSN 键名拼写host不是hostname[2002]网络层查 host/端口/socket 路径、容器网络、监听地址[1045]认证层看报错里的用户来源主机核对授权主机与密码caching_sha2_password相关认证层升级客户端库或用 TLS降级插件仅作临时手段[1049]库/权限层确认库名、CREATE DATABASE与账号对该库的权限[1040]服务端容量连接泄漏或max_connections太小查慢查询与连接池排查数据库连接失败的诀窍不是背错误码而是先分层再动手扩展、解析、网络、认证、库权限五层里先确定错误发生在哪一层再去改对应的地方。另外要记住 PHP 8.0/8.1 带来的行为差异——连接失败会抛异常而不是返回false所以老项目升级后第一件事是检查容错代码有没有跟着改成try/catch。