本文详解 WordPress 在 Apache 虚拟主机环境下无法连接 MariaDB 的典型原因，重点指出 localhost 与 127.0.0.1 在 PHP MySQLi 扩展中的语义差异，并提供可立即验证的端口显式指定方案及完整配置检查清单。
本文详解 wordpress 在 apache 虚拟主机环境下无法连接 mariadb 的典型原因，重点指出 `localhost` 与 `127.0.0.1` 在 php mysqli 扩展中的语义差异，并提供可立即验证的端口显式指定方案及完整配置检查清单。
在 WordPress + Apache + MariaDB 的本地部署中，出现“Error establishing database connection”却能在终端通过 mysql -u cr_user -p 成功登录，是极具迷惑性的常见问题。其根本原因往往不在权限或密码错误，而在于 PHP 的 MySQLi 扩展对 localhost 的特殊处理机制：当主机名设为 "localhost" 时，MySQLi 默认尝试通过 Unix 域套接字（socket）连接，而非 TCP/IP；而 MariaDB 配置若未正确指向该 socket 文件路径，或 socket 文件权限/位置不匹配，连接即会静默失败——这正是命令行 mysql 客户端能连通（它会自动探测 socket）、而 PHP 却报错的核心矛盾。
✅ 最直接有效的解决方案：强制使用 TCP 连接并显式指定端口
将所有数据库连接地址从 "localhost" 改为 "127.0.0.1:3306"（注意冒号分隔），明确告知 PHP 绕过 socket、走 TCP 协议：
// 测试文件 test_db.php 中的修正写法
<?php
$servername = "127.0.0.1:3306"; // ✅ 关键：添加 :3306
$username = "cr_user";
$password = "password";
$db = "tr_wordpress";
$conn = new mysqli($servername, $username, $password, $db);
if ($conn->connect_error) {
die("Connection failed: " . $conn->connect_error);
}
echo "Connected successfully via TCP on port 3306";
?>// wp-config.php 中对应修改
define('DB_NAME', 'tr_wordpress');
define('DB_USER', 'cr_user');
define('DB_PASSWORD', 'password');
define('DB_HOST', '127.0.0.1:3306'); // ✅ 同样添加端口
define('DB_CHARSET', 'utf8mb4'); // 推荐升级为 utf8mb4
define('DB_COLLATE', '');⚠️ 关键注意事项与补充检查项：
生产级WordPress REST API集成，用于管理文章、页面、媒体、WooCommerce产品、Elementor内容、SEO元数据、ACF及JetEngine字段
-
不要混用 localhost 与 127.0.0.1 的权限记录：MariaDB 中 'cr_user'@'localhost' 和 'cr_user'@'127.0.0.1' 是两个独立用户。若已执行 UPDATE mysql.user SET Host='127.0.0.1'...，请确认该操作成功且 FLUSH PRIVILEGES; 已执行；更稳妥的做法是同时授权两个 host：
CREATE USER 'cr_user'@'localhost' IDENTIFIED BY 'password'; CREATE USER 'cr_user'@'127.0.0.1' IDENTIFIED BY 'password'; GRANT ALL PRIVILEGES ON `tr_wordpress`.* TO 'cr_user'@'localhost'; GRANT ALL PRIVILEGES ON `tr_wordpress`.* TO 'cr_user'@'127.0.0.1'; FLUSH PRIVILEGES;
- 验证 MariaDB 监听状态：运行 sudo ss -tlnp | grep :3306，确保 mysqld 正在监听 127.0.0.1:3306（而非仅 ::1:3306 或 *:3306）。若只监听 IPv6，需在 /etc/mysql/mariadb.conf.d/50-server.cnf 中设置 bind-address = 127.0.0.1。
- 检查 PHP MySQLi 扩展是否启用：执行 php -m | grep mysqli，确保输出 mysqli；若无，需安装 sudo apt install php-mysql 并重启 Apache。
- 避免下划线与短横线混淆：数据库名 tr-wordpress 在 SQL 中需用反引号包裹（如 `tr-wordpress`），但 WordPress 配置中 DB_NAME 应严格匹配创建时的名称（示例中你使用了 tr_wordpress，请统一）。
? 总结：当 PHP 连接 MariaDB 失败而命令行成功时，优先怀疑 socket 连接路径问题。强制使用 127.0.0.1:3306 是最简洁、普适的绕过方案。配合权限双授权、端口监听验证和扩展检查，90% 的同类问题可快速定位解决。完成修改后，务必重启 Apache（sudo systemctl restart apache2）并清空浏览器缓存再测试。
