mysqli::debug 的“trace options”參數高級配置說明

M66 2025-06-01

mysqli::debug()是PHP 中一個相對少用但非常強大的調試工具，它允許開發者啟用底層的MySQLi 擴展的調試功能，從而分析連接、查詢執行等過程中的細節。在PHP 8.1 之後， mysqli::debug()的參數支持更加靈活，特別是其中的trace options ，為開發者提供了更強的定制能力。

本文將介紹如何使用和高級配置mysqli::debug()的trace options，並結合一些實例幫助你更好地理解其用途。

什麼是mysqli::debug() ？

mysqli::debug()是用於開啟調試輸出的方法，它實際上是mysqli_debug()函數的面向對象版本。它接受一個字符串參數，用於指定調試選項。

文法:

 mysqli::debug(string $options): bool

其中， $options就是我們要關注的重點—— 一組以逗號分隔的調試設置，例如：

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

參數詳解

在調試字符串中，常見的幾個選項包括：

d啟用調試
t啟用跟踪（trace）
o,<file>將調試輸出寫入指定文件
i,<file>從指定文件讀取配置
F記錄函數調用
A記錄所有調用（較為冗長）
n顯示網絡通信內容

你可以組合這些選項來實現對MySQLi 執行過程的詳盡監控。

示例：記錄調試信息到文件

假設你想將調試信息記錄到服務器的/tmp目錄下：

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

$mysqli = new mysqli("localhost", "user", "password", "database");

if ($mysqli->connect_error) {
    die("連接失敗: " . $mysqli->connect_error);
}

$result = $mysqli->query("SELECT * FROM users");
while ($row = $result->fetch_assoc()) {
    print_r($row);
}

$mysqli->close();
?>

這個配置將：

啟用調試（ d ）
啟用跟踪功能（ t ）
將輸出保存到/tmp/mysqli.trace.log

高級trace options 實戰技巧

1.記錄詳細函數調用棧

mysqli::debug("d:t:F:o,/tmp/trace_func.log");

啟用F參數後，日誌將包含每個MySQLi 函數的調用堆棧，這對於分析性能瓶頸尤其有用。

2.調試文件來自配置

你可以通過讀取配置文件，提前設置調試參數：

 // config.txt 內容：d:t:o,/tmp/from_config.log
mysqli::debug("i,/var/www/html/config.txt");

這樣可以避免硬編碼，提高靈活性，適用於大型項目或調試部署環境。

3.追踪網絡數據包（慎用）

如果你懷疑是客戶端與服務器之間的通信出了問題，可以啟用n ：

 mysqli::debug("d:t:n:o,/tmp/net_debug.log");

請注意：此選項生成的日誌可能包含敏感數據，應嚴格保護。

查看調試輸出

調試日誌生成後，可以通過如下命令查看：

 tail -f /tmp/mysqli.trace.log

在生產環境使用時，建議將日誌文件路徑替換為專用的日誌目錄，並設置合適的權限。

用途延伸：配合網頁追踪

結合前端URL，甚至可以用trace ID 關聯日誌，比如：

 $traceId = uniqid("trace_", true);
mysqli::debug("d:t:o,/tmp/$traceId.log");
header("X-Debug-Trace: https://m66.net/debug/$traceId.log");

這樣在瀏覽器開發者工具中就能拿到跟踪鏈接，快速定位問題。

總結

mysqli::debug()的trace options 為開發者提供了強大的調試手段。通過合理配置trace 字符串，可以實現：

函數調用分析
網絡調試
日誌集中管理
結合配置文件的可擴展性

在開發與測試階段，善用這些trace options，不僅可以節省大量排查時間，還能幫助你更深入地理解PHP 與MySQL 的交互機制。

mysqli::debug