在 VSCode 中執行 XDebug 偵錯 PHP 程式

基本說明

Xdebug 介紹

Xdebug 是專為 PHP 設計的擴充套件，提供強大的調試與性能分析功能，包括遠端調試、斷點設置和函式追蹤等。

VSCode 整合

可以將 Xdebug 與 VSCode 整合，以實現更高效的除錯流程，適合初學者和有經驗的開發者。

在使用 Xdebug 進行除錯時，您可能會遇到一些常見問題，例如連接失敗或設定錯誤。這些問題通常可以透過檢查 Xdebug 的設置來解決。在此，我們將探討一些常見的問題及其解決方案。

下載 xDebug

對於 Mac 用戶，您可以透過 Homebrew 安裝 Xdebug，這是相對簡單的方法。只需運行以下命令即可完成安裝：brew install [email protected]。

Windows 的 xDebug 版本可以在 https://xdebug.org/download#releases 下載

把下載的 PHP 8.3 TS VS16 (64 bit) 檔案，放在 php\ext 目錄下

為了確保 Xdebug 能夠正常運行，建議使用 Xdebug 的官方文檔，以獲取更詳細的設定說明和範例。

此外，確保在開發期間使用的 PHP 版本與 Xdebug 版本相匹配，例如，如果使用的是 PHP 8.3，就需要下載相應版本的 Xdebug。

修改 php.ini

在 php.ini 中加入下列的參數

[XDebug]
zend_extension = "php_xdebug-3.4.2-8.3-ts-vs16-x86_64.dll"
xdebug.mode = debug,develop
xdebug.discover_client_host = yes
xdebug.log_level = 0
xdebug.log = "W:/nginx/logs/xdebug_log.txt"
xdebug.start_with_request = yes
xdebug.idekey = VSCODE

[XDebug]
zend_extension = "php_xdebug-3.4.2-8.3-ts-vs16-x86_64.dll"
xdebug.mode = debug,develop
xdebug.discover_client_host = yes
xdebug.log_level = 0
xdebug.log = "W:/nginx/logs/xdebug_log.txt"
xdebug.start_with_request = yes
xdebug.idekey = VSCODE

執行 php -v 時應該會有 Xdebug 的訊息如下

在這個部分，我們將更深入地探討如何確認 Xdebug 是否已成功安裝並運行。可以執行 php -m 命令以查看當前啟用的擴充套件列表，這樣便能確認 Xdebug 是否在其中。

PS W:\nginx\html\twingo> php -v
PHP 8.3.20 (cli) (built: Apr  8 2025 22:02:24) (ZTS Visual C++ 2019 x64)
Copyright (c) The PHP Group
Zend Engine v4.3.20, Copyright (c) Zend Technologies
    with Xdebug v3.4.2, Copyright (c) 2002-2025, by Derick Rethans

PS W:\nginx\html\twingo> php -v
PHP 8.3.20 (cli) (built: Apr  8 2025 22:02:24) (ZTS Visual C++ 2019 x64)
Copyright (c) The PHP Group
Zend Engine v4.3.20, Copyright (c) Zend Technologies
    with Xdebug v3.4.2, Copyright (c) 2002-2025, by Derick Rethans

在撰寫 PHP 程式時，特別注意代碼邏輯的清晰和結構的合理性，這樣能夠使偵錯過程更為簡便。在此，我們提供一個範例，展示如何利用 Xdebug 進行有效的程序控制。

修改 VSCode 的 launch.json

加入兩個: “Listen for Xdebug” & “Launch current script in console” 設定檔如下:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch current script in console",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "externalConsole": false,
            "port": 9003
        },
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": [
                9003,
                9000
            ]
        }
    ]
}

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch current script in console",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "externalConsole": false,
            "port": 9003
        },
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": [
                9003,
                9000
            ]
        }
    ]
}

在進行偵錯時，您可以使用 Xdebug 的跟踪功能，這將幫助您了解函數是如何被調用的，並查看每次調用的變數狀態。這對於分析複雜的應用程式特別有用。

撰寫PHP程式

// FuncTest.php

<?php

function callbackFunction()
{
	echo 'Hello World!';
}

// 將 callbackFunction() 以字串參數的方式傳入 call_user_func()
// 這個時候會執行外部的函式 callbackFunction()
call_user_func('callbackFunction');

// 執行結果
// Hello World!

// FuncTest.php

<?php

function callbackFunction()
{
	echo 'Hello World!';
}

// 將 callbackFunction() 以字串參數的方式傳入 call_user_func()
// 這個時候會執行外部的函式 callbackFunction()
call_user_func('callbackFunction');

// 執行結果
// Hello World!