需配置Xdebug与VSCode PHP Debug插件协同工作，或使用PHP内置服务器启动调试端点；前者要求统一Xdebug配置并正确设置launch.json，后者适用于快速验证单接口逻辑。
如果您在使用 VSCode 开发 PHP 应用时需要调试 RESTful API 请求，但无法在断点处捕获请求或查看变量状态，则可能是由于调试环境未正确连接、Xdebug 配置缺失或请求未路由至可调试脚本。以下是多种可行的调试方法：
一、配置 Xdebug 并启用 VSCode 的 PHP Debug 插件
该方法通过本地 PHP 环境与 Xdebug 协同工作，在 VSCode 中启动监听，使 HTTP 请求触发断点。需确保 PHP CLI 和 Web 服务器（如 Apache 或 Nginx）均使用同一套 Xdebug 配置。
1、在 VSCode 扩展市场中安装 PHP Debug 插件（由 Felix Becker 提供）。
2、确认 PHP 安装目录下存在 xdebug.so（Linux/macOS）或 php_xdebug.dll（Windows），并在 php.ini 中启用扩展：`zend_extension=xdebug.so`。
立即学习“PHP免费学习笔记（深入）”；
3、在 php.ini 中添加以下 Xdebug 4 配置（适配 PHP 8.0+）：
`xdebug.mode=debug`
`xdebug.start_with_request=trigger`
`xdebug.client_host=127.0.0.1`
`xdebug.client_port=9003`
`xdebug.log=/tmp/xdebug.log`。
4、在 VSCode 中打开项目根目录，按下 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS），输入并选择 PHP: Select Interpreter，指定含 Xdebug 的 PHP 可执行路径。
5、在 VSCode 左侧活动栏点击调试图标，点击齿轮图标生成 launch.json，选择 PHP 环境，确认配置中 port 为 9003，且 pathMappings 正确映射本地项目路径与服务器文档根目录。
二、使用内置 PHP Web Server 启动调试端点
该方法绕过外部 Web 服务器依赖，直接利用 PHP 内置服务器运行脚本，并通过 Xdebug 自动附加调试器，适用于快速验证单个 REST 接口逻辑。
1、在项目根目录下创建 server.php，内容为：
`require $_SERVER['SCRIPT_FILENAME'];`。
2、在终端执行命令启动服务：php -S localhost:8000 server.php -t public/（假设 REST 入口为 public/index.php）。
3、在 VSCode 中设置断点于 public/index.php 或具体控制器方法内。
4、在浏览器或 curl 中发起请求，例如：curl -X GET http://localhost:8000/api/users，VSCode 将自动激活调试会话并停在断点处。
三、通过 Postman + Xdebug 触发参数化调试
该方法利用 Postman 的 URL 参数注入能力，主动向请求中添加 Xdebug 启动令牌，强制 Xdebug 连接当前 VSCode 调试监听器，适合测试特定路由或带 Query/Body 的 REST 请求。
1、确保 VSCode 的 PHP Debug 插件已启用监听，状态栏右下角显示 Listen on port 9003。
2、在 Postman 中新建请求，URL 格式为：http://localhost:8080/api/posts?XDEBUG_SESSION_START=PHPSTORM（注意：此处值可任意，但需与 xdebug.client_id 或默认行为匹配；VSCode 默认接受任意值）。
3、若使用 Nginx/Apache，确认其传递了 XDEBUG_SESSION_START 参数至 PHP-FPM，且未被 rewrite 规则过滤。
4、发送请求后，VSCode 将弹出调试会话提示，点击 Accept 即可进入断点调试流程。
四、使用 PHP Built-in Server 搭配 Xdebug 启动脚本调试
该方法将调试启动封装为可复用脚本，避免每次手动输入长命令，同时支持动态绑定端口与路径映射，适合多接口并行调试场景。
1、在项目根目录创建 debug-server.sh（Linux/macOS）或 debug-server.bat（Windows），内容为：
`php -dxdebug.mode=debug -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003 -S localhost:8080 -t public/`。
2、赋予脚本执行权限：chmod +x debug-server.sh。
3、运行脚本：./debug-server.sh，此时 PHP 内置服务器启动并携带完整 Xdebug 启动参数。
4、在 VSCode 中打开对应 PHP 文件，设置断点，使用 curl 或前端应用访问 http://localhost:8080/api/xxx，调试器将立即响应。
五、通过 Docker 容器内 PHP-FPM + Xdebug 连接宿主机 VSCode
该方法适用于使用 Docker Compose 运行 PHP 应用的团队开发环境，通过网络配置使容器内 Xdebug 主动连接宿主机的 VSCode 监听端口，实现跨容器调试。
1、在 docker-compose.yml 的 PHP 服务中添加环境变量：
`XDEBUG_MODE: debug`
`XDEBUG_CLIENT_HOST: host.docker.internal`
`XDEBUG_CLIENT_PORT: 9003`。
2、确保宿主机防火墙放行 9003 端口，并在 VSCode 的 launch.json 中设置 pathMappings，例如：
`"/var/www/html": "${workspaceFolder}"`。
3、启动容器：docker-compose up -d，检查 PHP 容器日志是否输出 Listening on 127.0.0.1:9003 类似信息。
4、在浏览器中访问容器暴露的 REST 接口地址（如 http://localhost:8080/api/todos），VSCode 将自动接收来自容器的调试连接请求。
