Xdebug 3 断点不触发的主因是 xdebug.mode 未设为 debug，必须显式配置 xdebug.mode=debug（可加 develop 等），旧版 remote_enable 等参数已失效且会干扰判断。
为什么 Xdebug 3 断点完全不触发
绝大多数“断点不触发”问题，根本原因不是扩展没装、也不是 IDE 没开监听，而是 xdebug.mode 没设或设错。Xdebug 3 默认关闭所有功能，xdebug.mode = debug 是调试通道的总开关，缺它等于没通电。旧配置里残留的 xdebug.remote_enable=1 或 xdebug.remote_autostart=1 全部失效，还会干扰判断。
常见错误现象：
- php -v 显示 Xdebug v3.x，但访问页面无任何调试日志
- VS Code 启动了 “Listen for Xdebug”，但断点图标变灰、不命中
-
xdebug_info()页面中 “Mode” 显示为空或不含debug
实操建议：
- 删掉 php.ini 中所有以
xdebug.remote_*开头的行（如xdebug.remote_host、xdebug.remote_port） - 确保只保留且正确设置：
xdebug.mode = debug（可追加其他模式，如debug,develop） - 运行
php --ri xdebug或访问xdebug_info()页面，确认 “Mode” 行明确显示debug
php.ini 中必须改写的几个关键配置项
Xdebug 3 不是“参数微调”，而是整套命名和逻辑重构。以下配置项必须按新规则重写，不能简单替换关键词：
-
zend_extension：必须指向完整路径（如/Applications/MAMP/bin/php/php8.2.12/lib/php/extensions/no-debug-non-zts-20220829/xdebug.so），不能只写xdebug -
xdebug.client_host：本地开发用127.0.0.1或localhost；Docker 容器内调试宿主机 PHP，需设为host.docker.internal（macOS/Windows）或实际网关 IP（Linux） -
xdebug.client_port：默认是9003，不是9000；VS Code、PhpStorm 新版默认连这个端口，端口不匹配会静默失败 -
xdebug.start_with_request：取值为yes或trigger（不是1或on），设为yes才能每次请求都尝试连接 IDE
性能影响提示：启用 xdebug.mode = debug 本身有轻微开销，但远低于 Xdebug 2 的默认行为；若仅需开发辅助（如美化 var_dump），可用 xdebug.mode = develop 替代，不开启调试通道。
VS Code launch.json 配置陷阱与修正
launch.json 错误往往不是语法问题，而是与 php.ini 中的调试触发方式冲突。最典型的是混用旧式环境变量和新式配置。
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
容易踩的坑：
- 在 “Launch currently open script” 配置中保留
"env": { "XDEBUG_CONFIG": "idekey=VSCODE" }—— Xdebug 3 已忽略该变量，应删除 - “Listen for Xdebug” 的
port写成9000，而 php.ini 中xdebug.client_port = 9003，导致连接被拒绝但无报错 -
pathMappings值错误，例如 Web 服务器 DocumentRoot 是/var/www/html，但映射写成"${workspaceFolder}/public"，断点位置无法对齐
推荐最小可靠配置（适用于本地 MAMP/XAMPP）：
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/Applications/MAMP/htdocs": "${workspaceFolder}"
}
}
]
}
注意：pathMappings 左侧必须是 PHP 进程看到的绝对路径（可通过 __DIR__ 或 $_SERVER['DOCUMENT_ROOT'] 确认），右侧是 VS Code 工作区路径。
如何验证 Xdebug 3 是否真正就绪
光看 php -v 有 Xdebug 字样不够，必须分层验证连接链路是否打通：
- 第一层：PHP 加载成功 → 运行
php --ri xdebug，确认输出含 “Enabled” 和 “Version => 3.x.x” - 第二层：调试模式启用 → 查看
xdebug_info()输出中 “Mode” 行是否包含debug，且 “Client host”、“Client port” 与预期一致 - 第三层：IDE 监听有效 → 在 VS Code 中启动 “Listen for Xdebug”，再终端执行
lsof -i :9003（macOS/Linux）或netstat -ano | findstr :9003（Windows），确认端口被 node 进程占用 - 第四层：请求触发调试 → 浏览器访问
http://localhost/test.php?XDEBUG_SESSION_START=1，同时查看xdebug.log（需提前配xdebug.log=/tmp/xdebug.log），搜索 “Connected to debugging client”
最容易被忽略的是第四层：很多人以为 xdebug.start_with_request = yes 就万事大吉，但若 VS Code 没提前启动监听，Xdebug 会等几秒后放弃，既不报错也不写日志——必须主动触发并查日志才能确认真实状态。
