Xdebug 基礎特性全覽：配置參數、核心函數與除錯技巧

Xdebug 基礎特性完整參考手冊

Xdebug 是 PHP 最強大的除錯與分析擴展。本文系統整理其核心配置指令、內建輔助函數，幫助開發者快速上手配置、理解行為、提升除錯效率。

一、核心配置指令 (php.ini)

二、核心輔助函數

1. 呼叫堆疊資訊

xdebug_call_file()    // 當前執行函數所在檔案名
xdebug_call_function() // 呼叫當前函數的函數名
xdebug_call_line()     // 呼叫處行號
xdebug_call_class()    // 呼叫者類別名 (若在類方法中)

範例：

<?php
function fix_string($a) {
    echo "Called @ " . xdebug_call_file() . ":" . xdebug_call_line() . " from " . xdebug_call_function();
}
$ret = fix_string(array('Derick'));
// 輸出: Called @ /home/httpd/html/test/xdebug_caller.php:12 from {main}
?>

2. 除錯開關

xdebug_disable() // 關閉錯誤堆疊顯示
xdebug_enable()  // 開啟錯誤堆疊顯示

3. 錯誤收集與查閱

// 開始收集 (不再直接輸出，存入緩衝)
xdebug_start_error_collection();

// 取得已收集錯誤 (格式化表格)，$clean=true 會清空緩衝
$errors = xdebug_get_collected_errors([$clean = false]);

// 停止收集 (不清空緩衝)
xdebug_stop_error_collection();

4. Header 與記憶體資訊

// 取得所有已發送 header (含 setcookie)
$headers = xdebug_get_headers();
// 回傳: ['X-Test', 'Set-Cookie: TestCookie=test-value']

// 當前腳本記憶體使用量 (bytes)
$mem = xdebug_memory_usage();

// 峰值記憶體使用量
$peak = xdebug_peak_memory_usage();

注意：PHP 5.2.1 前需編譯參數 --enable-memory-limit，之後內建支援。

5. 時間索引

// 回傳腳本啟動至今秒數 (float)
$t = xdebug_time_index();
// 範例: 0.00038 → 0.76581 (經過 25 萬次空迴圈)
?>

6. 檢測 Xdebug 是否啟用

if (xdebug_is_enabled()) { /* 除錯模式專用邏輯 */ }

三、實戰配置範例 (開發環境建議)

[xdebug]
zend_extension="php_xdebug.dll"
xdebug.default_enable=1
xdebug.max_nesting_level=512
xdebug.scream=1
xdebug.halt_level=E_WARNING|E_NOTICE
xdebug.force_display_errors=1
; 遠端除錯 (PhpStorm/VS Code) 另見 xdebug.remote_* 設定

四、常見坑點提醒

• xdebug.max_nesting_level 太低會誤殺正常遞歸 (如大型模板渲染)，建議設 512+。
• xdebug.scream=1 會暴露被 @ 隱藏的警告，可能導致舊專案大量噪音，建議新專案開啟、舊專案漸進式修正。
• 生產環境**務必關閉** xdebug.default_enable 並移除擴展，否則嚴重影響效能並洩露堆疊資訊。