本文详解 WordPress 在 Apache 虚拟主机环境下无法连接 MariaDB 的典型问题，重点分析 localhost 解析差异、MySQLi 连接端口缺失、用户权限绑定及 socket 通信机制，并提供可验证的调试步骤与修复代码。
本文详解 wordpress 在 apache 虚拟主机环境下无法连接 mariadb 的典型问题，重点分析 `localhost` 解析差异、mysqli 连接端口缺失、用户权限绑定及 socket 通信机制，并提供可验证的调试步骤与修复代码。
在 WordPress 部署中，出现“Error establishing database connection”却能通过命令行（如 mysql -u cr_user -p）正常登录 MariaDB，是典型的PHP MySQLi 连接机制与系统底层解析不一致所致。根本原因往往不在权限或密码错误，而在于 localhost 在不同上下文中的语义差异。
? 关键原理：localhost ≠ 127.0.0.1（在 MySQLi 中）
MySQLi 扩展对 localhost 有特殊处理：当主机名设为 localhost 时，PHP 默认尝试 Unix socket 连接（而非 TCP/IP），忽略端口配置。而 MariaDB 的 socket 路径若未正确配置、或 PHP 运行用户（如 www-data）无权访问该 socket 文件，连接即会静默失败。
但命令行 mysql -u cr_user -p 成功，是因为 mysql 客户端默认优先使用 TCP（即使写 localhost），或已正确读取 /etc/mysql/my.cnf 中的 socket 路径。这种不一致性正是问题根源。
✅ 正确解决方案：显式指定端口 + 统一连接方式
将所有数据库连接点（WordPress 配置 + 测试脚本）中的 localhost 替换为 127.0.0.1:3306，强制走 TCP/IP 协议：
1. 修改 WordPress 配置文件 wp-config.php：
生产级WordPress REST API集成，用于管理文章、页面、媒体、WooCommerce产品、Elementor内容、SEO元数据、ACF及JetEngine字段
define('DB_HOST', '127.0.0.1:3306'); // ⚠️ 关键：添加 :3306
define('DB_NAME', 'tr_wordpress');
define('DB_USER', 'cr_user');
define('DB_PASSWORD', 'password');
define('DB_CHARSET', 'utf8mb4');2. 更新测试 PHP 脚本（确保与 WordPress 一致）：
<?php
$servername = "127.0.0.1:3306"; // ✅ 强制 TCP，避免 socket 问题
$username = "cr_user";
$password = "password";
$dbname = "tr_wordpress";
$conn = new mysqli($servername, $username, $password, $dbname);
if ($conn->connect_error) {
die("Connection failed: " . $conn->connect_error);
}
echo "Connected successfully to MariaDB via TCP on port 3306";
?>? 提示：MariaDB 默认端口为 3306，若自定义过端口，请同步修改。
? 其他必须检查项（排除干扰）
-
确认 MariaDB 监听配置
检查 /etc/mysql/mariadb.conf.d/50-server.cnf：bind-address = 127.0.0.1 # ✅ 确保未设为 0.0.0.0 或注释掉 skip-networking = OFF # ✅ 必须关闭，否则禁用 TCP
修改后重启服务：sudo systemctl restart mariadb
-
验证用户权限是否绑定到 127.0.0.1（非 localhost）
登录 MariaDB 执行：SELECT User, Host FROM mysql.user WHERE User = 'cr_user'; -- 应返回 'cr_user' | '127.0.0.1' -- 若为 'localhost'，请重建用户： DROP USER 'cr_user'@'localhost'; CREATE USER 'cr_user'@'127.0.0.1' IDENTIFIED BY 'password'; GRANT ALL PRIVILEGES ON `tr_wordpress`.* TO 'cr_user'@'127.0.0.1'; FLUSH PRIVILEGES;
-
检查 SELinux / AppArmor（Ubuntu 22.04+ 常见）
若启用安全模块，可能阻止 Apache 访问网络：sudo aa-status | grep apache # 查看是否受限 sudo setsebool -P httpd_can_network_connect 1 # SELinux 临时放行
? 总结：三步快速定位
| 步骤 | 操作 | 验证方式 |
|---|---|---|
| 1. 强制 TCP | DB_HOST 改为 127.0.0.1:3306 | 测试脚本输出 "Connected successfully" |
| 2. 权限对齐 | 用户 Host 必须为 127.0.0.1（非 localhost） | SELECT ... FROM mysql.user 确认 |
| 3. 服务就绪 | sudo ss -tlnp | grep :3306 确认 MariaDB 监听 127.0.0.1:3306 | 无输出则检查 bind-address 和 skip-networking |
✅ 最终效果：WordPress 后台、前端、测试脚本全部可稳定连接，且不再依赖本地 socket 文件权限。此方案兼容 MariaDB 10.3+、Debian/Ubuntu/CentOS 等主流环境，是生产部署的推荐实践。
