WordPress“建立数据库连接时出错”：这是什么意思，以及怎么修

你打开站点，每一个页面——前台和 wp-admin 都一样——都被换成了一行灰色的句子：建立数据库连接时出错。 什么都渲染不出来，因为根本没法渲染。WordPress 连生成页面那一步都没走到。

有一个心智模型能让这个问题很快修好。WordPress 把你的全部内容——文章、页面、设置、用户——都存在 MySQL 数据库里，而不是存在文件里。每一次请求，它都会从 wp-config.php 读取四项登录信息，连接那个数据库，取出需要的东西。这个错误意味着连接被尝试了，然后被拒绝了。修复它，就是弄清楚它为什么被拒绝，而可能性只有三种。

三种原因，按可能性从高到低

1. wp-config.php 里某项凭据填错了——通常是换主机造成的。
2. 数据库服务器宕机或过载——通常是在你这边什么都没动的情况下发生的。
3. 数据库损坏——比较少见，而且它表现出来的样子不一样。

按这个顺序逐一排查。

第 1 步：核对这四项凭据

用 SFTP 或主机的文件管理器打开站点根目录的 wp-config.php。有四行定义了这个连接：

define( 'DB_NAME', 'your_database_name' );
define( 'DB_USER', 'your_database_user' );
define( 'DB_PASSWORD', 'your_database_password' );
define( 'DB_HOST', 'localhost' );

这四项都必须与主机分配给你的完全一致。打开主机控制面板的数据库一栏（在 cPanel 里叫「MySQL Databases」），逐字比对：

• DB_NAME — 主机常常会给名字加上你的账户前缀，比如 cpaneluser_wpdb。这个前缀是名字的一部分。
• DB_USER — 同样有前缀，而且这个用户必须被分配到那个数据库上，不能只是存在。
• DB_PASSWORD — 最常见的罪魁祸首。拿不准就在控制面板里重置，再把新值粘进去。留意末尾的空格，或是被自动替换成的弯引号。
• DB_HOST — 别想当然地填 localhost。很多主机用的是专门的数据库服务器，地址像 mysql.yourhost.com，有时还带 :port。控制面板会显示正确的值。

既然这四个值恰恰就住在这个文件里，那么重新生成一份干净、引号都正确的 wp-config.php，最稳妥的办法就是用 wp-config.php 生成器——填好四个数据库字段，把生成的结果覆盖到旧的那一段上。

几乎每一次迁移之后，单是这一步就能修好这个错误，因为在旧主机上正确的凭据，到了新主机上就成了错的。

第 2 步：确认数据库服务器确实在运行

如果凭据没错，错误却依然存在——尤其是它在你没做任何改动的情况下自己冒出来的——那么嫌疑就落在数据库服务器本身。

在虚拟主机上这很常见，而且通常是暂时的：MySQL 服务在流量高峰时被压垮，或者达到了每个账户的连接数上限，开始拒绝新的连接。它一般几分钟内就会恢复。在采取任何激烈手段之前，先稍等片刻再刷新。

要脱离 WordPress、单独测试凭据到底有没有效，可以在 wp-config.php 旁边放一个很小的脚本：

<?php
$link = mysqli_connect('localhost', 'your_database_user', 'your_database_password');
if (!$link) {
    die('Connection failed: ' . mysqli_connect_error());
}
echo 'Connected — the server and credentials are fine.';

用你真实的 DB_HOST、DB_USER 和 DB_PASSWORD。如果它打印出 Connected，说明你的登录信息是好的，问题在别处（数据库损坏，第 3 步）。如果它打印出连接错误，消息会告诉你是哪一种：「Access denied」表示用户名或密码错了；「Can’t connect to MySQL server」表示主机地址错了，或者服务确实宕了——该联系主机商了。一做完就立刻删掉这个脚本。

第 3 步：修复损坏的数据库

有一个迹象能把损坏和连接问题区分开：前台能打开，但 wp-admin 报错，或者反过来。如果连接真的被拒绝了，两边都该是死的。这样一边好一边坏，指向的是数据表损坏。

WordPress 自带一个修复工具。在 wp-config.php 里、「停止编辑」那行注释之上，加上一行：

define( 'WP_ALLOW_REPAIR', true );

然后在浏览器里直接访问这个 URL：

https://yoursite.com/wp-admin/maint/repair.php

这个页面不需要登录就能打开——这正是它的用意，因为你可能已经被锁在外面——它提供「Repair Database」和「Repair and Optimize Database」两个选项。运行它。

然后立刻从 wp-config.php 里删掉那一行。 只要它还在，互联网上的任何人都能访问那个 URL，对你的数据库运行一次修复。这不是可做可不做的收尾，而是在堵上你刚刚打开的一个洞。

第 4 步：当修复页面自己都连不上

如果修复页面自己也显示连接错误，那就没什么可修的了——数据库根本连不上，于是你又回到了第 1 步或第 2 步。到这一步，可靠的做法是从主机最近一次备份里还原数据库。大多数控制面板都会每天自动保留数据库快照；从昨晚的状态还原，几乎总比去追一个你连都连不上的损坏更快、更安全。

可以放心忽略的建议

「直接重装 WordPress 吧。」 这个错误关乎的是数据库连接，不是核心文件。重装只会把那些本来好好的文件换掉，而对真正坏掉的地方一点都碰不到。

「把 PHP 内存上限调高。」 内存耗尽是另一种错误，消息也不一样。调高上限对一个被拒绝的数据库连接毫无作用，只会掩盖你压根没去核对凭据这件事。

「清一下缓存。」 这个失败发生在 PHP 里，早于任何缓存能返回页面的时刻。连接被拒绝期间，清缓存什么都改变不了；只有在站点恢复之后才值得做。

「直接改数据库来修好它。」 在还没确认连接到底通不通之前就去 phpMyAdmin 手动改表，正是把一次临时故障变成永久数据丢失的做法。先确认连接；数据最后才碰，而且只从备份里碰。

还是没搞定？

如果测试脚本验证了凭据、服务器在运行、修复也能连上并报告没有错误，站点却仍然显示这条消息，那剩下的嫌疑对象就是某个用自己独立连接去访问数据库的插件——一个存了过时主机地址的缓存插件或数据库插件。用 SFTP 把 wp-content/plugins 改名为 plugins-off 来排除它。如果错误消失了，就把插件一个一个装回去，直到它再次出现。