php -S 内置服务器无法自动触发Xdebug断点，因其属CLI SAPI，不响应xdebug.start_with_request=yes；必须设为trigger并手动传参（如?XDEBUG_SESSION_START=1）才能激活调试。
php -S 启动的内置服务器本身不支持 Xdebug 自动连接，必须靠 xdebug.start_with_request=trigger + 手动触发（如 URL 参数）才能进断点。直接配成 yes 或依赖 CLI 模式会失败。
为什么 php -S 无法自动触发 Xdebug 断点
PHP 内置服务器是单进程 CLI SAPI，Xdebug 在 CLI 模式下默认不监听远程连接；它只在 Web SAPI（如 Apache/FPM）中响应 xdebug.start_with_request=yes。而 php -S 属于 CLI SAPI，所以即使 php.ini 里写了 xdebug.mode=debug，也只会启动调试器但不会主动连 VS Code。
-
xdebug.start_with_request=yes对php -S无效 —— 它只对 Web SAPI 生效 -
xdebug.start_with_request=trigger是唯一可靠方式，需显式传参（如?XDEBUG_SESSION_START=1）或用浏览器插件激活 - 不要指望
php -S启动后断点自动命中，VS Code 必须先运行 “Listen for Xdebug” 配置，再发带触发参数的请求
launch.json 必须匹配 xdebug.client_port
VS Code 的 PHP Debug 插件默认监听 9003 端口，而 Xdebug 3 默认 client_port 也是 9003 —— 但只要 php.ini 里改过，launch.json 就必须同步，否则连接直接超时。
- 检查 php.ini 是否含
xdebug.client_port=9003（不是 9000） -
launch.json中的"port": 9003必须与之完全一致 - 若用 Docker/WSL，
xdebug.client_host要设为宿主机 IP（如10.0.2.2），而非127.0.0.1 - 删掉 launch.json 里多余的配置项（如
runtimeExecutable、program），仅保留Listen for Xdebug模式
pathMappings 错一个字符，断点就失效
VS Code 不知道你代码在服务器上跑在哪，全靠 pathMappings 把本地路径和运行时路径对齐。内置服务器没有 DocumentRoot 概念，它的“根”就是 -t 指定目录下的文件路径，必须按实际解析结果写。
- 如果启动命令是
php -S localhost:8000 -t public，且请求/api/user映射到public/api/user.php，那么pathMappings左侧应填${workspaceFolder}/public/（注意结尾斜杠） - 右侧用
"${workspaceFolder}/public/"，不能写成"./public/"或相对路径 - Windows 用户注意反斜杠转义问题：路径映射里一律用正斜杠
/，VS Code 不认\ - 用
phpinfo()页面里的SCRIPT_FILENAME值确认真实路径，再反推映射关系
调试 REST 接口时，别漏掉 router.php 的处理
PHP 内置服务器不解析路由，所有请求都打到 router.php（或你指定的脚本）。如果你没手动 require 实际入口文件，Xdebug 根本没机会加载目标脚本，断点自然不触发。
立即学习“PHP免费学习笔记（深入）”；
- 创建
router.php，内容必须包含：require $_SERVER['SCRIPT_FILENAME'];或显式转发逻辑 - 启动命令要带这个文件：
php -S localhost:8000 router.php -t public - 断点设在
public/index.php或控制器里，而不是router.php—— 后者只是中转，变量作用域有限 - curl 测试时加触发参数：
curl "http://localhost:8000/api/users?XDEBUG_SESSION_START=1"
xdebug.log）是唯一能告诉你“连没连上、卡在哪一步”的证据。路径权限不对、client_host 写错、端口被占 —— 这些问题光看 VS Code 控制台或终端输出根本看不出，必须开日志、查文件。 
