Xdebug 是 PHP 開發調試利器，正確配置參數能最大化其價值。本文系統整理核心配置項、堆棧跟蹤、性能分析、遠程調試等關鍵設置。
安裝方式
預編譯模塊 (Windows)
; php.ini
zend_extension_ts = "C:/php/ext/php_xdebug.dll"
; 或 PHP 5.3+ 非線程安全
zend_extension = "C:/php/ext/php_xdebug.dll"
PECL 編譯安裝 (Linux/Mac)
pecl install xdebug
; 自動生成配置提示，按提示添加到 php.ini
基礎特性配置
| 參數 | 類型 | 默認 | 說明 |
|---|
| xdebug.default_enable | bool | On | 錯誤時自動顯示堆棧跟蹤，建議開啟 |
| xdebug.max_nesting_level | int | 256 | 最大嵌套層級，防無限遞歸，舊版默認100 |
| xdebug.cli_color | int | 0 | CLI 彩色輸出：1=有TTY時，2=強制 |
| xdebug.force_display_errors | bool | Off | 強制顯示錯誤，忽略 php.ini display_errors |
| xdebug.force_error_reporting | int | 0 | 強制錯誤報告級別 |
堆棧跟蹤配置
| 參數 | 類型 | 默認 | 說明 |
|---|
| xdebug.dump_globals | bool | On | 是否顯示超全局變量（$_GET,$_POST 等） |
| xdebug.dump_once | bool | On | 只在首次錯誤顯示超全局變量 |
| xdebug.dump_undefined | bool | Off | 顯示未定義的超全局變量值 |
| xdebug.show_exception_trace | bool | Off | 捕獲異常時也顯示堆棧跟蹤 |
| xdebug.show_local_vars | bool | Off | 顯示局部變量（信息量大，慎開） |
| xdebug.show_mem_delta | bool | Off | 顯示內存增量 |
| xdebug.collect_params | int | 0 | 函數參數收集級別 0-4 |
| xdebug.collect_return | bool | Off | 收集函數返回值 |
| xdebug.collect_vars | bool | Off | 收集變量作用域信息 |
| xdebug.dump.* | string | | 指定顯示的超全局變量，如 xdebug.dump.SERVER=REQUEST_METHOD,REQUEST_URI |
性能分析
| 參數 | 類型 | 默認 | 說明 |
|---|
| xdebug.profiler_enable | bool | Off | 啟用性能分析（生成 cachegrind 文件） |
| xdebug.profiler_enable_trigger | bool | Off | 通過 GET/POST/COOKIE 觸發（如 XDEBUG_PROFILE） |
| xdebug.profiler_output_dir | string | /tmp | 輸出目錄 |
| xdebug.profiler_output_name | string | cachegrind.out.%p | 輸出文件名模式（見下文） |
profiler_output_name 格式符號
| 符號 | 含義 | 示例 |
|---|
| %p | 進程 PID | cachegrind.out.1234 |
| %s | 腳本文件名 | cachegrind.out._var_www_index_php |
| %t | Unix 時間戳(秒) | cachegrind.out.1699900000 |
| %u | 微秒時間戳 | cachegrind.out.1699900000_123456 |
| %H | $_SERVER['HTTP_HOST'] | cachegrind.out.example.com |
| %R | $_SERVER['REQUEST_URI'] | cachegrind.out._api_user_login |
| %c | CWD CRC32 | cachegrind.out.1234567890 |
| %% | % 字符 | cachegrind.out.% |
推薦組合：cachegrind.out.%H_%R_%t 便於多站點、多接口、時間序列分析。
遠程調試
| 參數 | 類型 | 默認 | 說明 |
|---|
| xdebug.remote_enable | bool | Off | 啟用遠程調試 |
| xdebug.remote_host | string | localhost | IDE 所在主機 IP |
| xdebug.remote_port | int | 9003 | 調試端口 (Xdebug 3: 9003, Xdebug 2: 9000) |
| xdebug.remote_autostart | bool | Off | 自動嘗試連接 IDE |
| xdebug.remote_connect_back | bool | Off | 自動連接請求來源 IP（不安全，慎用） |
| xdebug.idekey | string | | IDE Key，如 PHPSTORM |
| xdebug.remote_log | string | | 調試連接日誌路徑 |
開發環境推薦配置模板
[xdebug]
zend_extension = "php_xdebug.dll"
xdebug.mode = debug,develop,trace,profile
xdebug.default_enable = 1
xdebug.max_nesting_level = 512
xdebug.cli_color = 2
xdebug.show_error_trace = 1
xdebug.show_local_vars = 0
xdebug.collect_params = 2
xdebug.collect_return = 1
xdebug.dump.GET = *
xdebug.dump.POST = *
xdebug.dump.SERVER = REQUEST_METHOD,REQUEST_URI,HTTP_USER_AGENT
xdebug.profiler_enable_trigger = 1
xdebug.profiler_output_dir = "C:/xdebug_profiler"
xdebug.profiler_output_name = "cachegrind.out.%H_%R_%t"
xdebug.remote_enable = 1
xdebug.remote_host = "127.0.0.1"
xdebug.remote_port = 9003
xdebug.idekey = "PHPSTORM"
xdebug.remote_log = "C:/xdebug_remote.log"
注意：Xdebug 3 統一使用 xdebug.mode 替代多個舊參數，配置更簡潔。
