前言介绍
数据库连接失败是网站运维中最常见的报错之一，无论是WordPress、Discuz!、Typecho还是各类企业建站系统，在迁移服务器、修改密码、更换域名或误操作配置文件后，都会出现“数据库连接失败”或“Error establishing a database connection”的提示。这类问题通常不是数据库本身损坏，而是站点配置文件中的数据库连接参数（主机地址、用户名、密码、数据库名）与实际数据库信息不匹配。本教程将带你从零开始，定位并核对站点配置文件中的每一项参数，确保数据库连接恢复正常。全程无需编程基础，只需按照步骤操作即可。
前置准备
1. 一台可以正常访问的电脑，建议使用Windows或macOS系统。
2. 能够登录服务器或虚拟主机的管理面板（如宝塔面板、cPanel、阿里云主机控制台等），或者拥有FTP/SFTP客户端（如FileZilla、WinSCP）。
3. 数据库管理工具（如phpMyAdmin、Navicat、DBeaver），或至少知道如何从主机面板进入数据库管理页面。
4. 网站根目录的访问权限，通常位于服务器上的 `/www/wwwroot/你的网站目录` 或 `/home/你的用户名/public_html` 等路径。
5. 记录下当前数据库的主机地址、端口、数据库名、用户名和密码，这些信息可以在主机面板的“数据库”或“MySQL”管理页面找到。
分步操作步骤
1. 定位站点配置文件
绝大多数PHP建站系统的数据库配置都集中在一个单独的文件中，文件名通常为 `wp-config.php`（WordPress）、`config.inc.php`（Discuz!）、`config.php`（Typecho、Laravel、ThinkPHP等）或 `database.php`（部分框架）。你需要通过FTP或主机面板的文件管理器找到这个文件。
- 使用FTP客户端：打开FileZilla，输入主机IP、FTP账号和密码（通常在主机面板的“FTP管理”中获取），连接成功后，在远程站点区域进入网站根目录（一般是 `public_html`、`wwwroot` 或 `htdocs`）。在文件列表中查找上述文件名，右键点击选择“查看/编辑”或直接下载到本地用记事本打开。
- 使用主机面板文件管理器：登录宝塔面板，点击左侧“文件”，进入网站根目录；如果是cPanel，点击“文件管理器”进入 `public_html` 文件夹。直接双击目标配置文件，即可在线编辑。
注意：如果找不到这些标准文件名，可以查看 `includes`、`config` 或 `application` 等子目录，有时配置文件会放在这些文件夹内。例如Discuz!的配置文件位于 `config/config_global.php` 和 `config/config_ucenter.php`。
2. 核对数据库主机地址（Host）
打开配置文件后，寻找类似以下内容的代码行：
```
define('DB_HOST', 'localhost');
```
或
```
'host' => '127.0.0.1',
```
或
```
$db['default']['hostname'] = 'localhost';
```
这一项就是数据库主机地址。你需要确认该地址与你的数据库实际地址一致。
- 如果数据库和网站运行在同一台服务器上（最常见的情况），主机地址通常填写 `localhost` 或 `127.0.0.1`。
- 如果数据库是独立服务器（如阿里云RDS、腾讯云CDB），主机地址应填写数据库服务的内网或外网连接地址，例如 `rm-bp1xxxxx.mysql.rds.aliyuncs.com`。注意：内网地址只能在同一云服务商的内网环境使用，外网地址则需开启数据库的外网访问权限（通常不建议开启，存在安全风险）。
- 如果使用了远程数据库，还需要检查端口号。默认MySQL端口是3306，如果数据库端口被修改，需要在配置文件中添加端口参数，例如 `'host' => '192.168.1.100:3307'` 或单独定义 `define('DB_PORT', '3307');`。部分系统（如WordPress）不支持直接在DB_HOST后加冒号端口，需要额外添加 `define('DB_PORT', '3307');` 这一行。
操作细节：将配置文件中DB_HOST的值与主机面板中数据库管理页面显示的“主机”或“连接地址”进行逐字对比，注意大小写和标点符号（例如localhost全部小写，127.0.0.1是数字和点）。
3. 核对数据库名、用户名和密码
在配置文件中继续找到以下三行（以WordPress为例）：
```
define('DB_NAME', 'your_database_name');
define('DB_USER', 'your_database_user');
define('DB_PASSWORD', 'your_database_password');
```
其他系统的写法类似，只是变量名不同，例如 `$db['default']['database']`、`$db['default']['username']`、`$db['default']['password']`。
- 数据库名：必须是主机面板中已经创建好的数据库名称，注意区分大小写（Linux系统严格区分大小写，Windows系统不区分但建议保持统一）。如果你在面板中看到数据库名是 `mywebsite_db`，但配置文件中写的是 `MyWebsite_DB`，就会连接失败。
- 数据库用户名：同样要与面板中创建的用户名完全一致。很多虚拟主机在创建数据库时会自动给用户名加上前缀，例如 `hosting123_myuser`，配置文件中必须包含这个完整前缀。
- 数据库密码：这是最容易出错的地方。密码可能包含特殊字符（如 `$`、`&`、`#`、`%`），这些字符在PHP字符串中需要进行转义，但大多数情况下直接复制粘贴即可。如果你在面板中重置了密码，务必同步更新配置文件中的密码。特别注意：密码两边的单引号或双引号不能缺失，且不能有多余的空格。
操作细节：打开主机面板的数据库管理页面，找到对应的数据库，点击“管理”或“查看用户”，核对数据库名、用户名。如果忘记密码，可以在面板中重置密码（通常需要同时更新配置文件和网站缓存）。重置后，将新密码复制粘贴到配置文件中，注意不要复制到多余的空格或换行符。
4. 检查数据库用户权限
即使数据库名、用户名和密码都正确，如果该用户没有被授予访问该数据库的权限，同样会连接失败。这一步容易被忽略。
- 通过phpMyAdmin检查：登录phpMyAdmin（通常在主机面板的“数据库”页面有快捷入口），在左侧选择你的数据库，点击顶部菜单的“权限”或“Privileges”。查看当前用户是否在“数据库特定权限”中拥有该数据库的“所有权限”（ALL PRIVILEGES）。如果没有，点击“添加用户”或“编辑权限”，勾选所有权限（或至少勾选SELECT、INSERT、UPDATE、DELETE、CREATE、ALTER、INDEX、DROP等），然后保存。
- 通过命令行检查（适用于有SSH权限的用户）：登录服务器后执行 `mysql -u your_user -p`，输入密码后，执行 `SHOW GRANTS FOR 'your_user'@'localhost';`，查看输出中是否包含 `GRANT ALL PRIVILEGES ON your_database.* TO ...`。如果没有，执行 `GRANT ALL PRIVILEGES ON your_database.* TO 'your_user'@'localhost';` 然后 `FLUSH PRIVILEGES;`。
操作细节：如果使用的是云数据库（如RDS），需要在云控制台的“账号管理”或“数据库管理”中，将用户与数据库进行授权绑定，并设置允许访问的主机（通常设为 `%` 表示所有IP，或设为网站服务器的内网IP）。这一步完成后，回到配置文件再次确认。
5. 测试数据库连接（可选但推荐）
为了确保配置文件的参数完全正确，你可以通过一个简单的PHP文件来测试连接，而不必直接刷新网站（因为网站可能因缓存导致误判）。
- 在网站根目录创建一个名为 `testdb.php` 的文件，用记事本写入以下代码（以WordPress为例，其他系统只需替换变量值）：
```php
$link = mysqli_connect(
'localhost', // 替换为你的DB_HOST
'your_user', // 替换为你的DB_USER
'your_password', // 替换为你的DB_PASSWORD
'your_database' // 替换为你的DB_NAME
);
if (!$link) {
die('连接失败: ' . mysqli_connect_error());
} else {
echo '数据库连接成功！';
mysqli_close($link);
}
?>
```
- 保存文件后，在浏览器中访问 `http://你的域名/testdb.php`。如果显示“数据库连接成功”，说明配置文件的参数完全正确，问题可能出在网站缓存或PHP扩展上。如果显示“连接失败”及具体错误信息（如“Access denied for user”表示用户名或密码错误，“Unknown database”表示数据库名错误，“Can't connect to MySQL server”表示主机地址或端口错误），则根据错误提示返回第2-4步重新核对。
- 测试完成后，务必删除 `testdb.php` 文件，避免被他人利用获取数据库信息。
6. 保存并清除缓存
确认参数无误后，保存配置文件。如果通过FTP编辑，保存后会自动上传覆盖；如果通过面板在线编辑，直接点击“保存”或“确定”。然后进行以下操作：
- 清除网站缓存：如果你使用了缓存插件（如WP Super Cache、W3 Total Cache）或服务器缓存（如Redis、Memcached），需要清除所有缓存。对于WordPress，可以登录后台（如果还能访问）点击“设置”中的“清除缓存”，或直接删除 `wp-content/cache` 目录下的所有文件。
- 重启PHP服务（可选）：在宝塔面板中，点击“服务”->“PHP”->“重启”；在cPanel中，可以在“软件”->“MultiPHP Manager”中重启。这一步可以确保PHP重新加载配置文件。
- 刷新网站前台页面：如果仍然显示数据库连接错误，尝试在浏览器中强制刷新（Ctrl+F5）或清除浏览器缓存。如果错误变为“页面无法加载”或“500错误”，说明配置文件语法有误，请检查引号、分号是否完整，不要遗漏任何符号。
常见问题
- 问题1：配置文件中的密码包含特殊字符，导致连接失败。
解答：如果密码包含 `$`、`\` 或 `"`，在PHP字符串中需要转义。例如密码是 `pass$word`，在配置文件中应写为 `'pass$word'`（单引号内不需要转义），但如果使用双引号，则必须写成 `"pass\$word"`。最稳妥的做法是：在主机面板中重置密码为纯字母数字组合，然后更新配置文件。
- 问题2：数据库主机地址填了 `localhost` 但连接失败，换成 `127.0.0.1` 却成功。
解答：部分服务器配置中，`localhost` 可能通过Unix套接字连接，而 `127.0.0.1` 强制使用TCP/IP连接。如果PHP的MySQL扩展不支持套接字或套接字路径错误，就会导致 `localhost` 失败。解决方案：在配置文件中统一使用 `127.0.0.1` 或服务器分配的内网IP。
- 问题3：修改配置文件后，网站仍然显示数据库连接错误。
解答：可能是网站启用了opcache（PHP代码缓存），导致旧的配置文件被缓存。解决方法：在PHP配置中关闭opcache，或重启PHP服务（宝塔面板中重启PHP即可）。如果是WordPress，还可以在 `wp-config.php` 中添加 `define('WP_CACHE', false);` 临时禁用缓存。
- 问题4：数据库连接成功，但网站页面显示“建立数据库连接时出错”。
解答：这通常不是配置文件的问题，而是数据库服务器负载过高、连接数耗尽或数据库表损坏。可以登录phpMyAdmin，在数据库上点击“检查表”或“修复表”；或者联系主机商检查数据库服务状态。
- 问题5：使用了远程数据库，但网站和数据库不在同一内网。
解答：云数据库通常有内网和外网两个地址。如果网站服务器和数据库在同一云服务商的同一区域，必须使用内网地址（延迟低且免费）。如果必须使用外网地址，需要在数据库的安全组或白名单中放行网站服务器的公网IP，并开启外网访问权限（注意：这会产生流量费用且存在安全风险）。
收尾总结
数据库连接失败的核心原因90%以上是站点配置文件中的参数与数据库实际信息不匹配。通过本教程的六步操作——定位配置文件、核对主机地址、核对库名用户密码、检查用户权限、测试连接、清除缓存——你能够系统性地排查并修复问题。记住，每次修改配置文件后都要保存并重启PHP服务，同时清除网站和浏览器缓存。如果所有参数都正确但问题依旧，请检查数据库服务本身是否正常运行，或联系服务器运维人员查看错误日志。掌握这些技能后，你不仅能解决数据库连接问题，还能举一反三，迁移网站或搭建新站点时更加得心应手。