mysqli::debug 在Docker或虚拟机环境下的使用技巧

M66 2025-06-01

在 PHP 开发中，mysqli::debug() 是一个鲜为人知但非常有用的函数。它可以用来调试 MySQLi 扩展的内部执行过程，尤其在处理复杂数据库连接或查询问题时提供了极大的帮助。

本文将介绍如何在 Docker 或虚拟机环境中启用并使用 mysqli::debug() 来提升调试效率。

一、什么是 mysqli::debug()？

mysqli::debug() 是 PHP MySQLi 扩展提供的调试工具，其作用是将 MySQLi 的调试信息输出到指定的文件中。它不会输出到标准输出或浏览器，而是写入服务器上的日志文件。

调用方式非常简单：

mysqli::debug("d:t:o,/tmp/client.trace");

参数 "d:t:o,/tmp/client.trace" 的含义是：

d：调试信息；
t：线程信息；
o：输出到文件；
/tmp/client.trace：输出文件路径。

注意：使用此函数前必须启用 MySQL 客户端库的调试支持，否则此函数调用无效。

二、在 Docker 或虚拟机中启用调试功能

在 Docker 容器或虚拟机中使用该函数时，需要注意两个前提：

PHP 必须以 CLI 或 FPM 模式运行，并启用 mysqlnd 驱动；
容器或虚拟机中的 PHP 必须编译时带有调试支持。

1. 确认 PHP 支持调试功能

运行以下命令检查 PHP 是否支持 mysqli 调试：

php -i | grep 'Client API version'

如果结果中包含 mysqlnd，则表示支持。否则可能需要重新编译 PHP，或安装包含 mysqlnd 的 PHP 镜像。

2. Dockerfile 示例（启用 mysqli debug）

如果你使用 Docker，可以在 Dockerfile 中配置如下：

FROM php:8.2-cli

RUN docker-php-ext-install mysqli \
    && echo "mysqli.allow_local_infile=On" >> /usr/local/etc/php/php.ini

# 可选：挂载调试文件路径
VOLUME /tmp

然后在 PHP 中编写如下代码测试：

<?php
mysqli::debug("d:t:o,/tmp/client.trace");

$mysqli = new mysqli("db.m66.net", "root", "password", "test");

if ($mysqli->connect_errno) {
    echo "连接失败: " . $mysqli->connect_error;
    exit();
}

$result = $mysqli->query("SELECT * FROM users");

while ($row = $result->fetch_assoc()) {
    print_r($row);
}

$mysqli->close();

运行此脚本后，可以在 /tmp/client.trace 文件中查看调试信息。

3. 虚拟机环境说明（如使用 Vagrant）

在虚拟机中使用与在本机或 Docker 中无异。唯一需要注意的是 PHP 进程要有写入你设定日志文件路径的权限，例如 /tmp 或你指定的挂载目录。

三、调试日志样例

调试日志内容大致如下（节选）：

>mysql_real_connect
>mysql_send_query
<mysql_read_query_result
...

通过这些日志，可以定位连接失败的原因、慢查询的执行过程，甚至发现因 DNS 配置错误而导致的延迟。

四、安全性建议

在生产环境中应避免启用 mysqli::debug()，因为它会泄漏数据库连接信息、查询内容等敏感数据。仅推荐在开发或测试环境中使用，并注意清理生成的日志文件。

五、小结

在 Docker 或虚拟机环境下使用 mysqli::debug() 并不复杂，关键在于：

确保 PHP 使用的是 mysqlnd；
容器或虚拟机中设置好日志路径的权限；
调试完毕后及时禁用或删除日志。

通过合理使用这个工具，可以在排查数据库问题时更加高效、精准。

如果你也有类似的调试需求，不妨试试看！

mysqli::debug