小皮面板怎么开启 Xdebug 调试 PHP 代码？

学完这篇，你可以在小皮面板（phpStudy v8）里为指定 PHP 版本开启 Xdebug，并让 VSCode 或 PhpStorm 成功停在断点。

第一步：确认 PHP 版本和 Xdebug 状态

这一步要确认你正在给哪个 PHP 版本开调试，做完后你能知道该改哪个 php.ini。打开小皮面板 Windows 版 phpStudy v8.1，左侧点「软件管理」，在「PHP」分类里看已安装版本，例如 php-7.4.3-nts。记下版本号和是否带 nts。点该版本右侧「设置」→「php.ini」，在文件里搜索 xdebug。如果没有，说明还没装；如果有，先看是 Xdebug 2 还是 Xdebug 3，后面参数不同。

注意：Xdebug 的 dll 必须和 PHP 版本、TS/NTS、VC 编译器、32/64 位完全匹配。装错会导致 PHP 启不来。Linux 版小皮面板入口通常在「软件商店」→「已安装」→「PHP-7.4」→「设置」→「配置文件」，参数一样。

第二步：启用或安装 Xdebug 扩展

这一步要让 PHP 加载 Xdebug，做完后 phpinfo() 里能看到 xdebug。如果小皮面板自带扩展，在「软件管理」→「PHP」→ 对应版本右侧「设置」→「扩展」，勾选「Xdebug」，点「保存」。如果列表里没有，去 xdebug.org/wizard 粘贴 phpinfo() 内容，按提示下载对应 dll，放到 D:\phpstudy_pro\Extensions\php\php-7.4.3-nts\ext，再在 php.ini 里加一行：

zend_extension="D:\phpstudy_pro\Extensions\php\php-7.4.3-nts\ext\php_xdebug.dll"

注意：路径用绝对路径，不要同时加载多个 xdebug 扩展。

第三步：写入调试参数

这一步要告诉 Xdebug 把调试请求发到本机 IDE，做完后断点才可能生效。继续在「软件管理」→「PHP」→「设置」→「php.ini」里添加配置。

Xdebug 3 写法：

[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=PHPSTORM

Xdebug 2 写法：

[xdebug]
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000
xdebug.remote_autostart=1
xdebug.idekey=PHPSTORM

注意：Xdebug 3 默认端口是 9003，Xdebug 2 默认端口是 9000。IDE 里监听端口必须和这里一致，否则断点不生效。

第四步：重启 PHP 并验证

这一步是让配置生效并检查扩展是否加载。回到小皮面板「首页」，在运行状态区域点「重启」，或到「软件管理」→「PHP」→ 对应版本点「停止」再「启动」。新建 D:\phpstudy_pro\WWW\test.php，内容写：

<?php phpinfo();

浏览器访问 http://localhost/test.php，搜索 xdebug，能看到版本号即成功。也可以用命令行验证：

D:\phpstudy_pro\Extensions\php\php-7.4.3-nts\php.exe -m | findstr xdebug

输出 xdebug 就说明扩展已加载。

第五步：配置 IDE 接收调试

这一步让编辑器接住 Xdebug 请求，做完后能逐行断点。VSCode 安装扩展「PHP Debug」，新建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/www": "D:\\phpstudy_pro\\WWW"
      }
    }
  ]
}

按 F5 开始监听。浏览器访问页面时加 ?XDEBUG_SESSION_START=PHPSTORM，或安装 Xdebug helper 扩展并开启 Debug。

PhpStorm 路径：File → Settings → PHP → Debug，Debug port 填 9003，勾选 Can accept external connections；再点 Run → Start Listening for PHP Debug Connections。

注意：项目路径映射写错时，断点会变灰。VSCode 的 port 必须和 php.ini 中 xdebug.client_port 一致。

小结

• 在「软件管理」→「PHP」→「设置」→「扩展」启用 Xdebug，必要时手动放 dll。
• Xdebug 3 用 xdebug.mode=debug 和端口 9003；Xdebug 2 用 remote_enable=1 和端口 9000。
• 改完 php.ini 必须重启 PHP。
• 用 phpinfo() 或 php -m | findstr xdebug 验证扩展。
• IDE 监听端口、路径映射要和面板配置一致。