Xdebug 堆疊追蹤完整指南：配置參數與變數顯示詳解

Xdebug 堆疊追蹤完整指南：配置參數與變數顯示詳解

當 Xdebug 啟用時，PHP 在顯示通知、警告或錯誤時會自動輸出堆疊追蹤資訊。這項功能能依據開發需求靈活配置顯示內容，是除錯利器。然而，大量資訊的處理與呈現會拖慢腳本執行，因此 Xdebug 採取保守策略預設僅顯示基礎資訊，並透過多項設定讓開發者按需啟用詳細輸出。

堆疊追蹤中的變數控制

Xdebug 在堆疊追蹤時會顯示變數資訊，但收集與顯示變數會消耗大量資源。為平衡效能與實用性，Xdebug 提供 xdebug.collect_params 設定，支援 0–5 共六個層級，控制函數參數的顯示細節。以下以範例腳本說明各層級差異：

<?php
function foo( $a ) {
    for ($i = 1; $i < $a['foo']; $i++) {
        if ($i == 500000) xdebug_break();
    }
}
set_time_limit(1);
$c = new stdClass;
$c->bar = 100;
$a = array(
    42 => false,
    'foo' => 912124,
    $c,
    new stdClass,
    fopen( '/etc/passwd', 'r' )
);
foo( $a );
?>

層級 0（預設）

僅顯示函數名稱，不顯示任何參數資訊。

層級 1

顯示參數類型與元素數量，例如 foo(array(5))。

層級 2

同層級 1，但於 Web 環境下滑鼠懸停可查看完整變數內容（CLI 模式無提示）。

層級 3

顯示完整變數內容，受 xdebug.var_display_max_children、xdebug.var_display_max_data、xdebug.var_display_max_depth 限制。

層級 4

顯示完整變數內容與變數名稱，例如 foo($a = array(...))。

層級 5

以 PHP 序列化格式輸出變數內容，不含名稱（Xdebug 2.3+ 新增）。

核心相關設定詳細說明

xdebug.cli_color

• 類型：integer，預設 0，Xdebug 2.2+
• 1：CLI 模式下連接 tty 終端時以顏色輸出 var_dump 與追蹤資訊（Windows 需安裝 ANSICON）。
• 2：強制啟用顏色輸出，無視 tty 與 ANSICON，結尾可能出現逸出碼。

xdebug.collect_includes

• 類型：boolean，預設 1
• 控制是否將 include、require 等引用檔案名稱寫入追蹤檔案。

xdebug.collect_params

• 類型：integer，預設 0
• 控制函數追蹤與堆疊追蹤時的參數收集層級（0–5），詳見上表。Xdebug 2 將資料直接寫入磁碟，不佔用記憶體，僅需足夠磁碟空間。

xdebug.collect_vars

• 類型：boolean，預設 0
• 啟用後 Xdebug 會在特定範圍收集變數名稱（不含值），供 xdebug_get_declared_vars() 使用。會逆向解析 PHP 代碼，效能較慢。

xdebug.dump.* 系列

• 類型：string，預設空值
• 支援 COOKIE、FILES、GET、POST、REQUEST、SERVER、SESSION 七大超全域變數。
• 設定範例：
  xdebug.dump.SERVER = REMOTE_ADDR,REQUEST_METHOD
xdebug.dump.GET = *

xdebug.dump_globals / dump_once / dump_undefined

• dump_globals（boolean，預設 1）：總開關，控制是否顯示超全域變數。
• dump_once（boolean，預設 1）：1 僅首次錯誤顯示，0 每次錯誤皆顯示。
• dump_undefined（boolean，預設 0）：1 顯示未定義的超全域變數鍵值。

xdebug.manual_url

• 類型：string，預設 https://www.php.net，Xdebug 2.2.1+
• 指定函數追蹤與錯誤訊息的連結說明來源，建議設定為最近的鏡像站。

xdebug.show_exception_trace

• 類型：integer，預設 0
• 設為 1 時，即使例外被捕獲，仍會顯示堆疊追蹤。

xdebug.show_local_vars

• 類型：integer，預設 0
• 非零值時，錯誤堆疊追蹤頂層顯示所有區域變數，資訊量大，預設關閉。

xdebug.show_mem_delta

• 類型：integer，預設 0
• 非零值時，人類可讀追蹤檔顯示函數呼叫間的記憶體差異。

變數顯示限制三參數

• xdebug.var_display_max_children（integer，預設 128）：陣列元素/物件屬性最大顯示數，-1 為不限制。
• xdebug.var_display_max_data（integer，預設 512）：字串最大顯示長度，-1 為不限制。
• xdebug.var_display_max_depth（integer，預設 3）：巢狀深度上限 1023，-1 表最大值。以上三參數不影響遠端除錯。

實用內建函數

xdebug_get_declared_vars()

回傳當前作用域已定義變數名稱陣列，需啟用 xdebug.collect_vars。

<?php
class strings {
    static function fix_strings($a, $b) {
        foreach ($b as $item) { }
        var_dump(xdebug_get_declared_vars());
    }
}
strings::fix_strings(array(1,2,3), array(4,5,6));
?>
/* 回傳:
array(
    0 => 'a',
    1 => 'b',
    2 => 'item'
)
*/

xdebug_get_function_stack()

回傳類似堆疊追蹤的陣列，含檔案、行號、參數等資訊。

xdebug_get_stack_depth()

回傳目前堆疊深度（主腳本為 0，每層呼叫 +1）。

xdebug_print_function_stack([string $message [, int $options]])

手動輸出當前函數堆疊，支援自訂訊息與選項 XDEBUG_STACK_NO_DESC（隱藏表頭，適用於自訂錯誤處理器，Xdebug 2.3+）。

函數監控 API（Xdebug 2.4+）

• xdebug_start_function_monitor(array $functions)：開始監控指定函數/方法（支援 Class::staticMethod、Object->method），區分大小寫。
• xdebug_stop_function_monitor()：停止監控。
• xdebug_get_monitored_functions()：取得受監控函數列表。