WordPress 提示「建立数据库连接时出错」：先核 wp-config 与数据库服务，再查表损坏与磁盘配额

前台或后台整页只剩一行英文/中文提示「建立数据库连接时出错 / Error establishing a database connection」，刷新依旧，wp-admin 也进不去------这和今天槽位里写过的表单「提交成功但收不到邮件」、Elementor 编辑器空白、登录 Cookie/CDN 重定向环、502/503、PHP 白屏/严重错误、WP-Cron、媒体上传、固定链接 404、Woo 支付回调、HTTPS 重定向、小程序真机白屏不是一类故障。PHP 进程多半还在跑，卡在 WordPress 连不上 MySQL/MariaDB：wp-config.php 里的 DB_*、主机侧数据库服务是否存活、配额与磁盘是否写满、表是否损坏、迁移后凭证是否仍指向旧库。

更稳的顺序是：先分清是 凭证写错 / 数据库服务停了或拒绝连接 / 磁盘或 inode 写满 / 表损坏需 repair / 迁移后库名主机未改 → 核对 DB_NAME DB_USER DB_PASSWORD DB_HOST → 看主机面板数据库服务与连接数 → 再考虑 WP_ALLOW_REPAIR 与磁盘配额。别一上来就重装整站，也别在没备份时直接在生产跑修复。

先分清：凭证错误 vs 数据库服务挂了 vs 表损坏 vs 磁盘配额 vs 迁移后指错库

「建立数据库连接时出错」常见落在五条线上，别和白屏 Fatal、SMTP、编辑器 REST 混着改：

wp-config.php 的 DB_* 写错或被改乱：库名、用户、密码、主机（含端口/socket）任一不对，立刻整站这句提示。
主机侧 MySQL/MariaDB 服务停、重启中、或达到最大连接数 ：面板里服务红灯、或 Too many connections；WordPress 侧表现同样是连不上。
表损坏 / 崩溃：个别站点在高压、异常断电、磁盘满之后，核心表损坏；有时前台偶发、有时稳定报连接错（视驱动与错误映射而定）。
磁盘配额 / inode 用尽：数据目录无法写临时文件或扩展 ibdata，服务表现为拒绝连接或异常退出。
迁移、换主机、从备份恢复后仍指向旧凭证 ：新机器上的 wp-config 还写着旧内网主机名、旧库名，或面板里重建了库却没同步密码。

先记下：是否刚迁站/改过密码、主机面板数据库服务是否绿灯、磁盘使用率、错误是否整站稳定复现。再决定是改配置还是修服务。

第一步：核 wp-config 的 DB_NAME / DB_USER / DB_PASSWORD / DB_HOST

能 SSH 或文件管理器时，先打开站点根目录的 wp-config.php（不要用主题里的同名文件）：

对照主机面板「数据库」页，逐项核对：
- DB_NAME：库名是否一字不差（含前缀）；
- DB_USER / DB_PASSWORD：用户是否对该库有权限；刚在面板「重置密码」后，配置文件必须同步；
- DB_HOST：多数共享主机是 localhost；部分是 127.0.0.1、带端口的 127.0.0.1:3306、或云厂商给出的内网地址 / 套接字路径。localhost 与 127.0.0.1 在部分环境走 socket vs TCP，表现不同，不要想当然互改。
检查是否有第二份配置、环境变量或部署脚本在部署时覆盖了这四个常量；容器/流水线站点尤其常见「面板改了密码、镜像里仍是旧值」。
用面板自带的 phpMyAdmin / Adminer，或本机 mysql 客户端，用同一组 用户密码试登目标库。面板能进、WordPress 不能 → 回头盯 DB_HOST 与站点 PHP 实际连的地址；两边都不能 → 定界在账号或服务，而不是主题。
改完配置后清一下对象缓存/持久缓存插件（若还能进文件层），避免旧连接信息被缓存层误用；一次只改一类变量并刷新前台。

预期：凭证与面板一致且客户端能登库后，若提示消失，即可收工；仍报错则进第二步看服务与连接数，而不是继续改主题。

第二步：主机面板里看数据库服务状态、连接数与重启窗口

配置无误仍连不上时，转到主机/云面板：

看 MySQL / MariaDB 服务是否运行；共享主机常提供「重启数据库」或工单入口，VPS/云主机则看 systemd / 容器健康检查。
看资源：CPU、内存、最大连接数是否打满；短时流量或爬虫把连接占满时，WordPress 也会统一报「建立数据库连接时出错」。
查主机通知：是否正在做存储迁移、自动备份锁表过久、或厂商侧维护。
安全组 / 防火墙：若 DB_HOST 指向远程库，确认应用机出站与数据库入站端口放行；仅本机库则不必对公网开 3306。
生产注意：重启数据库前确认无长事务与备份任务；记录重启时间点，便于和监控曲线对照。

预期：服务恢复且连接数回落后，站点应能重新拿到连接；若服务反复崩溃，优先查磁盘与错误日志（第三、四步），不要只循环点重启。

关于迁站后主机名、内网地址、套接字路径如何与面板「数据库主机」字段对齐，以及换机后常见的「旧库凭证残留」，可对照 WordPress 迁移与托管排查清单把「配置层」和「主机服务层」分开验证，再决定是改 DB_HOST 还是在新面板重建授权。

第三步：磁盘配额、inode 与数据目录写满

数据库服务不稳定或启动即挂时，先看存储：

面板或 df -h / df -i 看磁盘与 inode 是否用尽；日志、备份、wp-content/uploads、临时目录堆积都能把盘写满。
数据库数据目录所在分区满时，InnoDB 可能无法扩展表空间，表现为拒绝连接、崩溃恢复循环、或 WordPress 侧统一连接错误。
清理前先辨认大户：过期备份、旧站点副本、主机自动备份残留；不要直接删 ibdata / 当前库文件。
配额型共享主机：即使整盘未满，账号 inode / 容量配额 到顶同样会让 MySQL 用户目录写失败------以面板「配额」为准，而不是只看机器总容量。
腾出空间并确认服务正常启动后，再刷新站点；若仍偶发连接错，进入表修复。

预期：配额与磁盘恢复余量后，服务能稳定运行；WordPress 提示随服务恢复而消失。仍有单表报错再走第四步。

第四步：WP_ALLOW_REPAIR 与表损坏（先备份）

仅在确认凭证与服务正常、且日志或 phpMyAdmin 提示表损坏 / crashed 时使用：

先做库级备份 （面板一键备份或 mysqldump）。没有备份不要在生产启修复。
维护窗临时在 wp-config.php 加入：

php 复制代码

define('WP_ALLOW_REPAIR', true);

浏览器访问：

text 复制代码

https://你的域名/wp-admin/maint/repair.php

按需选「修复」或「修复并优化」。完成后立刻删掉 上述常量，避免任何人触发修复页。

也可在 phpMyAdmin 对报错表执行「修复表」；优先处理 wp_options、wp_users、wp_posts 等核心表（前缀以你站点为准）。
修复后若仍偶发连接错，查慢查询与连接泄漏插件，而不是反复 repair。

预期：损坏表修复后读写恢复；repair 页不应长期保留入口。

第五步：迁站 / 换主机后凭证与 DB_HOST 残留

刚从备份恢复、搬到新主机、或把「测试库」切成「生产库」时：

重新从新面板 复制库名、用户、密码、主机，覆盖旧 wp-config；不要沿用旧机内网主机名。
确认新库里确实导入了完整表；空库 + 正确密码也会让 WordPress 在后续步骤报错，但连接阶段应先能连上------若连「建立数据库连接」都过不了，仍回第一步。
多环境（本地 / 预发 / 生产）不要共用一份未区分的 wp-config；用环境变量或独立文件，避免发版把生产密码打成测试值。
若使用只读副本或代理中间件，确认应用应连主库写地址；误连已下线的旧主库会稳定复现本提示。
改完后用前台首页与 wp-login.php 各刷一次；能出登录表单即表示 PHP ↔ 数据库通路已通。

验证方法

面板或客户端用同一组 DB_* 能登录目标库。
数据库服务绿灯，连接数未打满，磁盘与 inode 有余量。
前台与 wp-login.php 不再出现「建立数据库连接时出错」；后台可正常进入。
若曾启用 WP_ALLOW_REPAIR，确认常量已删除；修复前后备份仍保留一份。
迁站场景：新主机名/套接字与面板一致，旧内网地址已从配置中清除。

小结

整站只剩「建立数据库连接时出错」时，按 DB_* 凭证 → 数据库服务与连接数 → 磁盘/配额 → 表修复 → 迁站残留主机名 这条线推进，每次只改一类变量并留下备份。把它和 PHP Fatal 白屏、SMTP 投递、编辑器 REST、登录重定向区分开，能少走很多重装整站的弯路。