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

mysqli::debug