xdebug 3 断点生效的前提是 cli 环境正确加载并配置 xdebug：需确认 php --ini 加载的 php.ini 路径、php -m | grep xdebug 有输出、php --ri xdebug 显示 mode=debug；必须使用 xdebug.mode=debug、xdebug.client_port=9003、xdebug.start_with_request=trigger 和 zendextension 路径四条配置，禁用所有 remote* 参数；vs code 的 launch.json 中 port 和 pathmappings 必须与 cli 配置严格一致，且启动前需打开项目根目录、启用监听、通过 url 参数或插件触发调试。
直接能用的前提是：你本地 PHP CLI 环境已加载 Xdebug 3，且 php --ini 显示的 php.ini 路径是你改过的那个——很多人断点不生效，根本不是 VS Code 配置问题，而是 CLI 根本没读到 Xdebug。
确认 CLI 下 Xdebug 是否真启用（不是 Apache 的 php.ini）
VS Code 调试走的是 PHP CLI 进程，不是 Web 服务器。必须验证 CLI 是否加载了 Xdebug：
- 终端执行
php --ini，记下 Loaded Configuration File 路径（比如C:\php\php.ini或/usr/local/etc/php/8.2/php.ini） - 执行
php -m | grep xdebug，有输出才表示 CLI 加载成功；若无输出，说明你改的可能是 Apache 的 php.ini，白配 - 执行
php --ri xdebug，检查 Version 是 v3.x，且 mode 字段包含debug，Supports phpinfo() 为 enabled
php.ini 必须写的四条 Xdebug 3 配置（删掉所有 xdebug.remote_*）
Xdebug 3 彻底废弃了 xdebug.remote_* 系列参数，保留它们会导致静默失效或启动报错：
-
zend_extension=xdebug（Linux/macOS）或zend_extension="C:/php/ext/php_xdebug.dll"（Windows，路径含引号且用正斜杠） -
xdebug.mode=debug（不是on、不是1，写错等于没开） -
xdebug.client_port=9003（Xdebug 3 默认端口，不是 9000；改了就必须同步改 VS Code） -
xdebug.start_with_request=trigger（需手动触发，更安全；设为yes会每次请求都连调试器） - 强烈建议加：
xdebug.log=C:/tmp/xdebug.log（Windows）或xdebug.log=/tmp/xdebug.log（macOS/Linux），出问题直接看日志，比猜快十倍
launch.json 的 port 和 pathMappings 必须对齐真实路径
VS Code 启动监听后收不到连接，90% 出在这两处：
-
port值必须和xdebug.client_port完全一致（比如都是9003） -
pathMappings是“左服务器右本地”：左边填 PHP 进程看到的绝对路径，右边填你 VS Code 打开的文件夹路径 - 本地开发常见情况（如 Apache DocumentRoot 是
C:/xampp/htdocs）："C:/xampp/htdocs/": "${workspaceFolder}/" - Docker 环境（容器内路径是
/app）："/app/": "${workspaceFolder}/" - Windows 用户注意：路径里用
/，不是\；两边结尾斜杠要统一（都带或都不带）
启动调试前必须做的三件事
别急着按 F5，漏一步断点就变空心圆：
- 在 VS Code 中打开项目根目录（不是只开一个 .php 文件），确保
${workspaceFolder}指向正确位置 - 点击左侧调试图标 → 顶部选
Listen for Xdebug→ 点绿色 ▶️ 启动监听（此时 VS Code 在 9003 端口等待连接） - 触发调试：在浏览器访问 URL 末尾加
?XDEBUG_SESSION_START=VSCODE（idekey要匹配），或装 Xdebug Helper 浏览器插件一键激活
最易被忽略的是 pathMappings 左右路径的字符级一致性——多一个空格、少一个斜杠、大小写不一致，断点就无法命中。xdebug.log 日志里第一行通常就写着 “Could not map …”，直接告诉你哪条映射失败了。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
