WordPress显示“建立数据库连接时出错”，说明PHP没有拿到可用的数据库连接，页面主题和插件此时通常还没有开始执行。刚迁移、改域名或换服务器后出现，先核对wp-config.php中的数据库名称、用户、密码与主机；运行中的站点突然报错，则优先检查MySQL或MariaDB服务、磁盘、内存、连接数和网络。不要先重装WordPress，也不要把数据库密码贴到工单或聊天记录中。
先按发生时间分成两条排查线
| 出现方式 | 优先怀疑 | 第一项验证 |
|---|---|---|
| 迁移或改配置后立即出现 | 连接参数、授权、数据库未导入、主机名或端口错误 | 对照新环境实际数据库信息 |
| 原本正常，突然全站报错 | 数据库服务停止、资源耗尽、连接拥塞、磁盘已满 | 检查服务状态和系统日志 |
| 只有部分请求或间歇报错 | 连接数上限、慢查询、数据库重启、网络抖动 | 按故障时间对齐应用与数据库日志 |
| 命令行可连，网页仍报错 | PHP运行环境不同、缓存旧配置、连接池或多节点配置不一致 | 确认Web进程读取的站点目录与配置文件 |
先记录故障开始时间、最近一次迁移或配置变更，以及影响范围。若是生产站点，排查前保留数据库和站点文件的可恢复备份；不要在服务不稳定时连续重启并覆盖日志。
迁移后报错：逐项核对wp-config.php
WordPress官方文档明确把数据库连接信息放在wp-config.php中，核心字段是DB_NAME、DB_USER、DB_PASSWORD和DB_HOST。核对时只确认字段是否与新服务器一致，不要把密码直接输出到终端历史或公开截图。
grep -nE "DB_(NAME|USER|HOST)" wp-config.php
wp config get DB_NAME
wp config get DB_USER
wp config get DB_HOST数据库前缀$table_prefix写错通常会表现为找不到已有站点数据或进入安装流程，而不是最初的连接失败。真正需要先确认的是：数据库是否已创建、导入是否完成、用户是否存在、该用户是否获得目标数据库权限，以及主机名和端口是否属于当前环境。
localhost、127.0.0.1和独立数据库主机名不能随意互换。不同PHP与数据库客户端可能分别走Unix Socket或TCP；远程数据库还受到监听地址、防火墙和安全组约束。面板里显示“数据库正常”也不能证明WordPress所用账号、主机和连接方式正确。
突然宕机：先看服务与资源，不要先改密码
systemctl status mariadb
systemctl status mysql
journalctl -u mariadb --since "-30 min"
journalctl -u mysql --since "-30 min"
df -h
free -m服务器通常只运行MySQL或MariaDB其中之一，选择实际存在的服务检查。重点寻找被系统终止、磁盘写满、权限变化、InnoDB恢复失败、连接过多或反复重启等线索。若数据库因内存不足被终止，可结合1GB内存WordPress的内存分配与OOM排查继续检查，不要只提高PHP内存上限。
磁盘满时不要直接删除不认识的数据库文件。先识别占用来源，保留数据目录和日志的完整性，再按备份策略处理。数据库能够重新启动也不等于故障已解除；如果资源压力没有消失，连接错误还会再次出现。
用站点运行环境验证连接
在正确的WordPress目录、对应PHP版本和站点文件所属用户下运行WP-CLI。官方wp db check会读取WordPress数据库常量并调用数据库检查工具，因此比把密码写进临时命令更适合验证当前站点配置。
wp db check命令若提示认证失败，回到账号、密码和授权；提示无法解析主机或连接被拒绝，检查主机名、端口、Socket、监听地址与防火墙；提示数据库不存在，核对数据库名称和导入目标。更系统的MySQL状态与日志判断可参考MySQL连接与运行状态排查清单。
如果wp db check通过而浏览器仍失败，比较命令行和Web请求使用的PHP版本、环境变量、容器、挂载目录和配置文件。多节点站点还要确认每个节点都已更新，不要只修复其中一台。
表损坏不是第一步
数据库表需要修复时，连接本身通常已经建立，日志也会出现具体表错误。不要把“建立数据库连接时出错”一律归因于表损坏，更不要在没有备份时批量修复。若确认需要启用WordPress自带修复能力，只在维护窗口临时加入WP_ALLOW_REPAIR，完成后立即删除该常量，并复查未授权访问风险。
从备份恢复前，要确认备份时间、数据库版本、字符集以及恢复会覆盖哪些新数据。电商订单、表单提交和会员数据在故障期间仍可能变化，不能把“有备份”理解为可以无条件回滚。
面板环境还要检查哪些覆盖项
面板创建的数据库账号、容器环境变量、托管平台密钥和旧的wp-config.php可能同时存在。真正生效的是Web进程当前读取的配置。使用面板管理站点时，可以查看极跃圈收录的宝塔面板信息页；面板能帮助查看服务和数据库，但连接参数、授权范围、备份完整性仍需逐项验证。
恢复后怎样确认不是暂时可用
- 首页、登录、文章详情和一次需要数据库写入的低风险操作均能正常完成。
- 数据库服务在观察窗口内没有再次重启，磁盘与内存不再持续逼近上限。
- 应用日志和数据库日志不再新增认证失败、连接拒绝或连接数耗尽记录。
wp db check在站点运行环境中通过，且没有把密码暴露到命令历史。- 重新启动PHP进程或容器后仍能连接，证明不是旧进程或缓存暂时保留了配置。
常见问题
修改数据库密码后，WordPress为什么马上报错？
数据库端密码和wp-config.php必须同步。还要确认改的是WordPress实际使用的账号，并检查托管平台或容器是否用环境变量覆盖了文件配置。
localhost改成127.0.0.1能解决吗？
不一定。两者可能分别使用Socket和TCP，只有在确认数据库监听方式、端口和权限后才能判断。盲目替换可能把原问题变成新的连接路径错误。
数据库服务正常，为什么WordPress仍然连不上？
服务进程存在不代表账号、授权、目标数据库、监听地址和网络路径都正确。应在站点实际运行环境中执行连接检查，并对照数据库日志定位拒绝原因。
可以直接重装WordPress解决数据库连接错误吗？
通常不可以。重装不能修复停止的数据库服务、错误授权或资源耗尽，还可能覆盖配置。先确认故障层和备份，再决定是否需要恢复文件。
