必须用Xdebug 3，php.ini与launch.json的端口、模式、路径映射须严格一致；验证需执行php -v（含Xdebug v3.x）、php --ini（确认配置文件路径）、php --ri xdebug（mode含debug且Supports phpinfo()为enabled）；最小配置含zend_extension=xdebug、xdebug.mode=debug、xdebug.start_with_request=trigger、xdebug.client_port=9003、xdebug.idekey=VSCODE；launch.json须用插件生成并仅改port和pathMappings；触发调试需URL加?XDEBUG_SESSION_START=1或Xdebug Helper插件激活。
VS Code 调试 PHP 必须用 Xdebug 3（2026 年已全面弃用 Xdebug 2），且 php.ini 和 launch.json 的端口、模式、路径映射三者必须严格一致，差一个字符都会导致“connection refused”或断点不命中。
确认 Xdebug 3 已加载且版本匹配
别信“我装过了”，必须终端里亲手验证：
- 运行
php -v，输出里必须含Xdebug v3.x（不是 v2.x，也不是只写“with Xdebug”） - 运行
php --ini，确认你改的php.ini是 Loaded Configuration File 那行显示的路径（不是 .user.ini 或其他） - 运行
php --ri xdebug，检查Supports phpinfo()为 enabled，且mode字段包含debug - 如果输出为空或报错，说明扩展没加载成功——重点查
zend_extension路径是否拼错、文件是否存在、是否与 PHP 架构（TS/NTS、x86/x64）不匹配
php.ini 中必须写的 Xdebug 3 配置项
Xdebug 3 默认关闭所有调试能力，只写 zend_extension 不会触发调试。以下是最小可用配置（删掉所有旧版 xdebug.remote_* 参数）：
zend_extension=xdebug xdebug.mode=debug xdebug.start_with_request=trigger xdebug.client_host=127.0.0.1 xdebug.client_port=9003 xdebug.idekey=VSCODE xdebug.log=/tmp/xdebug.log xdebug.log_level=7
说明：
立即学习“PHP免费学习笔记（深入）”；
-
xdebug.start_with_request=trigger表示需手动触发（如加?XDEBUG_SESSION_START=1），比yes更安全，避免全站请求都连调试器 -
xdebug.client_port=9003是 Xdebug 3 默认端口，9000是 Xdebug 2 的，混用必失败 -
xdebug.log强烈建议开启，连接失败时直接看日志比猜配置快十倍；路径确保 PHP 进程有写权限 - 若 PHP 运行在 Docker 容器中，
xdebug.client_host应设为host.docker.internal（Windows/macOS）或宿主机网关 IP（Linux）
VS Code 中 launch.json 的关键字段
必须用 VS Code 插件自动生成模板（「运行」→「打开配置」→ 选 PHP），不要手写空文件。生成后只改这几项：
-
"port": 9003—— 必须和php.ini中xdebug.client_port完全一致 -
"pathMappings"—— 本地开发可简化为{"\/": "${workspaceFolder}/"}；若用 Docker，左边填容器内绝对路径（如"/var/www/html/"），右边填本地项目路径 - 删掉所有
runtimeExecutable或env相关字段，除非你明确需要 CLI 调试 - 不要加
"request": "attach"，本地开发一律用"request": "launch"
常见错误：pathMappings 键值颠倒、路径末尾斜杠不统一（/var/www/html vs /var/www/html/）、用了 Windows 风格反斜杠 \。
触发调试时浏览器和代码要配合
VS Code 点击 ▶️ 启动 “Listen for Xdebug” 后，它只是监听端口，真正触发靠 PHP 请求本身：
- 浏览器访问时加参数：
http://localhost/index.php?XDEBUG_SESSION_START=1（idekey值必须匹配xdebug.idekey） - 或安装浏览器插件 Xdebug Helper（Chrome/Firefox），切换为 Debug 模式，自动注入 cookie
- PHP 代码中也可硬编码触发：
xdebug_break();，但仅限临时排障，勿提交到仓库 - CLI 脚本调试需额外设环境变量：
XDEBUG_CONFIG="idekey=VSCODE client_port=9003" php script.php
最易忽略的一点：Xdebug 3 不再响应 xdebug.remote_autostart=1 这类旧参数，哪怕你写了也无效；一切以 xdebug.mode 和 xdebug.start_with_request 为准。
