在PHP项目中对接MySQL数据库时，连接失败是开发阶段和线上环境都可能出现的问题，合理的错误日志记录和准确的日志分析能够快速定位问题根源，减少排查时间。
PHP连接MySQL的常见扩展与错误触发
目前PHP连接MySQL主要使用mysqli扩展和PDO扩展，两种扩展在连接失败时都会触发错误，但错误默认的处理方式不同。默认情况下，PHP的错误会输出到页面或者记录到配置的错误日志文件中，具体取决于php.ini的相关配置。
mysqli扩展连接示例
<?php
// 数据库连接配置
$host = '127.0.0.1';
$username = 'test_user';
$password = 'wrong_password'; // 故意设置错误密码
$database = 'test_db';
$port = 3306;
// 尝试连接MySQL
$conn = new mysqli($host, $username, $password, $database, $port);
// 检查连接是否成功
if ($conn->connect_error) {
// 连接失败，记录错误日志
error_log('mysqli连接MySQL失败：' . $conn->connect_error);
}
?>
PDO扩展连接示例
<?php
$dsn = 'mysql:host=127.0.0.1;port=3306;dbname=test_db;charset=utf8';
$username = 'test_user';
$password = 'wrong_password';
try {
$pdo = new PDO($dsn, $username, $password);
$pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
} catch (PDOException $e) {
// 捕获连接异常并记录日志
error_log('PDO连接MySQL失败：' . $e->getMessage());
}
?>
错误日志的配置方法
要让PHP的错误日志能够正确记录，首先需要配置php.ini中的相关参数，核心配置项如下：
- log_errors：设置为On，开启错误日志记录功能
- error_log：指定错误日志文件的存储路径，例如/var/log/php/php_error.log
- error_reporting：设置错误报告级别，建议设置为E_ALL，记录所有类型的错误
- display_errors：线上环境设置为Off，避免错误信息直接输出到页面，开发环境可设置为On方便调试
修改完配置后需要重启PHP服务让配置生效，也可以在代码中临时修改配置，示例如下：
<?php
// 临时开启错误日志
ini_set('log_errors', 'On');
// 设置日志文件路径
ini_set('error_log', '/tmp/php_mysql_error.log');
// 设置错误报告级别
error_reporting(E_ALL);
// 关闭页面错误显示
ini_set('display_errors', 'Off');
?>
常见连接错误与日志分析
连接MySQL失败时，错误日志中会记录对应的错误信息，常见的错误类型及分析方式如下：
| 错误日志内容示例 | 错误原因 | 解决方向 |
|---|---|---|
| Access denied for user 'test_user'@'127.0.0.1' (using password: YES) | 用户名或密码错误，或者该用户没有从当前主机连接的权限 | 检查数据库用户名密码是否正确，确认用户权限配置 |
| Unknown database 'test_db' | 指定的数据库不存在 | 确认数据库名称是否正确，检查数据库是否已被创建 |
| Connection refused | MySQL服务未启动，或者端口、主机地址配置错误 | 检查MySQL服务运行状态，确认主机地址和端口是否正确 |
| Can't connect to MySQL server on '127.0.0.1' (111) | MySQL服务未监听对应端口，或者防火墙拦截了连接 | 检查MySQL监听配置，确认防火墙是否放行对应端口 |
自定义错误日志增强分析效率
除了记录PHP默认的错误信息，还可以在代码中自定义日志记录逻辑，增加更多上下文信息，方便后续分析。例如记录连接的时间、当前请求的URL、调用的代码位置等信息：
<?php
function log_mysql_error($error_msg) {
$log_content = sprintf(
"[%s] MySQL连接错误：%s，请求URL：%s，调用文件：%s，调用行号：%sn",
date('Y-m-d H:i:s'),
$error_msg,
$_SERVER['REQUEST_URI'] ?? 'CLI',
debug_backtrace()[0]['file'] ?? '未知',
debug_backtrace()[0]['line'] ?? '未知'
);
error_log($log_content, 3, '/var/log/php/mysql_custom_error.log');
}
// 使用自定义日志函数记录错误
$conn = new mysqli('127.0.0.1', 'test_user', 'wrong_password', 'test_db');
if ($conn->connect_error) {
log_mysql_error($conn->connect_error);
}
?>
通过自定义日志函数，可以将更多和连接错误相关的上下文信息记录下来，在排查问题时能够更快速定位到是哪个请求、哪段代码触发的连接错误，大幅提升问题排查效率。