vscode 中 php cli 脚本调试失败通常因 launch.json 缺失、xdebug 未正确配置或 cli/web 环境混淆；需按 xdebug 3 规范配置 php.ini 与 launch.json，或使用“launch current script”、内置服务器混合调试、环境变量临时启用等方法解决。
如果您在 VSCode 中运行 PHP 命令行脚本时无法进入断点或调试器无响应，则可能是由于 launch.json 配置缺失、Xdebug 未正确挂载或 CLI 环境与 Web 环境混淆所致。以下是实现 PHP CLI 脚本调试的多种配置方法：
一、使用 Xdebug 3 配合 launch.json 单步调试
该方法通过 VSCode 内置调试器连接本地 Xdebug 扩展，要求 PHP CLI 已加载 Xdebug 3，并启用远程调试模式。Xdebug 需配置为以“debug”模式监听 CLI 请求，而非仅响应 Web 服务器流量。
1、确认 PHP CLI 已启用 Xdebug：在终端执行 php -m | grep xdebug，输出应包含 xdebug；若无，需编辑 php.ini 启用 extension=xdebug.so（Linux/macOS）或 xdebug.dll（Windows）。
2、在 php.ini 中添加以下 Xdebug 3 配置项：
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log
3、在 VSCode 工作区根目录下创建 .vscode/launch.json，写入以下配置：
立即学习 “PHP 免费学习笔记（深入）”；
{
“version”: “0.2.0”,
“configurations”: [
{
“name”: “Listen for Xdebug”,
“type”: “php”,
“request”: “launch”,
“port”: 9003,
“pathMappings”: {
“/var/www/html”: “${workspaceFolder}”
},
“cwd”: “${workspaceFolder}”
}
]
}
4、在 PHP 脚本中设置断点，点击 VSCode 左侧调试面板的绿色三角形启动监听，再在终端执行 php script.php，调试器将自动附加并停在断点处。
二、通过“Launch Currently Open Script”快速启动调试
此方法无需手动启动监听，VSCode 会自动调用 PHP CLI 并注入 Xdebug 参数，适用于单文件快速验证，要求 Xdebug 3.1+ 且启用 xdebug.start_with_request=trigger 或 yes。
1、确保 launch.json 中已存在如下配置块（可追加至 configurations 数组）：
{
“name”: “Launch Current Script”,
“type”: “php”,
“request”: “launch”,
“program”: “${file}”,
“cwd”: “${fileDirname}”,
“externalConsole”: false,
“env”: {
“XDEBUG_MODE”: “debug”
}
}
2、打开待调试的 PHP 文件（如 test.php），按 Ctrl+F5（Windows/Linux）或 Cmd+F5（macOS）直接启动调试。
3、若提示“无法连接到调试器”，检查是否已关闭其他 IDE 或终端中正在监听 9003 端口的进程：lsof -i :9003（macOS/Linux）或 netstat -ano | findstr :9003（Windows）。
三、使用 PHP 内置 Web 服务器配合 CLI 调试（混合场景）
当脚本依赖 $_SERVER 变量或需模拟 Web 上下文运行 CLI 任务时，可借助 PHP 内置服务器临时托管入口，再通过 HTTP 触发 CLI 逻辑，实现断点捕获。
1、新建一个 web-entry.php 文件，内容为：
require __DIR__ . ‘/your-cli-script.php’;
// 此处可传递模拟的 argv 或 $_SERVER
2、在 launch.json 中添加配置：
{
“name”: “PHP Built-in Server + Debug”,
“type”: “php”,
“request”: “launch”,
“program”: “${workspaceFolder}/web-entry.php”,
“port”: 9003,
“pathMappings”: {
“${workspaceFolder}”: “${workspaceFolder}”
}
}
3、启动调试后，在浏览器访问 http://127.0.0.1:8000/web-entry.php，执行流程将进入 your-cli-script.php 中的断点。
四、禁用 Xdebug 对 CLI 性能干扰的临时方案
部分生产环境或 CI 流程中需保留 Xdebug 扩展但禁止其介入 CLI 执行，可通过环境变量精准控制加载行为，避免调试配置污染非调试场景。
1、在终端中执行调试前，显式启用 Xdebug：
XDEBUG_MODE=debug php script.php
2、若使用 Composer 脚本，可在 composer.json 中定义：
“scripts”: {
“debug”: “XDEBUG_MODE=debug php index.php”
}
3、运行 composer debug 即可触发带 Xdebug 的 CLI 执行，且不修改全局 php.ini。
