VSCode中PHP断点不触发主因是xdebug.mode=debug未生效、xdebug.client_port与VSCode监听端口9003不一致，或launch.json缺失有效监听配置及pathMappings路径映射错误。
VSCode 中 PHP Debug 插件无法触发断点，90% 是因为 xdebug.mode=debug 没生效、xdebug.client_port 与 VSCode 监听端口不一致，或 launch.json 缺失有效监听配置 —— 不是插件装错了，而是通信链路在某一处断了。
确认 Xdebug 已加载且版本匹配 PHP
PHP 8.5.5 环境下必须使用 Xdebug 3.3+（Xdebug 4 尚未正式发布），旧版 Xdebug 2 的 xdebug.remote_enable 配置会直接导致静默失败。
- 执行
php -v确认输出含with Xdebug字样；若无，说明扩展未启用 - 执行
php --ri xdebug查看Version和Supports phpinfo()字段，确保不是disabled - 执行
php --ini找到真实生效的php.ini路径，打开后检查zend_extension行是否指向存在的.so文件（如/usr/local/lib/php/pecl/20230831/xdebug.so） - 若用 Docker，
php -m | grep xdebug必须在容器内执行，宿主机查不到
php.ini 中必须设置的四项核心参数
Xdebug 3 默认关闭远程调试，只靠 zend_extension 加载远远不够。漏掉任意一项都会让 VSCode 收不到连接请求。
-
xdebug.mode=debug：唯一启用调试模式的方式，xdebug.remote_enable=1已被废弃 -
xdebug.start_with_request=trigger：避免全站请求都连调试器；设为yes可省去 URL 参数，但开发环境慎用 -
xdebug.client_host=127.0.0.1：本地调试写死此值；Docker 容器中需改为host.docker.internal（macOS/Windows）或宿主机网关 IP（Linux） -
xdebug.client_port=9003：Xdebug 3 默认端口，9000是 Xdebug 2 的，混用必报Connection refused - 务必删除所有
xdebug.remote_*开头的旧参数，它们会覆盖新配置
VSCode launch.json 必须校准的三项
launch.json 不是“生成完就完事”，它要和 Xdebug 的行为严格对齐，否则 VSCode 在监听，Xdebug 却往别处发包。
立即学习“PHP免费学习笔记（深入）”；
- 模板选
Listen for Xdebug，不是Launch Built-in Web Server（后者不走 DBGp 协议） -
"port": 9003必须与php.ini中xdebug.client_port完全一致 -
"pathMappings"是路径映射关键项：若 PHP 运行在/var/www/html，而你本地项目在/Users/me/project，就得写"/var/www/html": "${workspaceFolder}" - 如果用 Laravel Homestead/Valet/Docker，
pathMappings错误会导致断点灰色不可用（VSCode 找不到对应文件）
触发调试会话的三种可靠方式
URL 参数最常用，但 REST API 或 CLI 脚本场景下容易失效；xdebug_break() 是兜底手段，但仅限 CLI 或已知入口脚本。
- Web 请求：在 URL 后加
?XDEBUG_SESSION_START=VSCODE（idekey值必须匹配php.ini中的xdebug.idekey） - CLI 脚本：终端执行前加环境变量
XDEBUG_CONFIG="idekey=VSCODE" php script.php - 硬编码断点：在 PHP 代码中插入
xdebug_break();，VSCode 会立即捕获（无需 URL 参数） - 浏览器插件（如 Xdebug Helper）可一键切换开关，但依赖 Cookie，跨域或 API 请求时不可靠
最容易被忽略的是 xdebug.log —— 建议始终开启：xdebug.log=/tmp/xdebug.log，权限设为 644，连接失败时第一手日志比猜配置快十倍；另外，PHP-FPM 或 Apache 修改 php.ini 后必须重启对应进程，仅重启 VSCode 没用。
