Xdebug 3 配置指南：解决 VSCode + MAMP 下断点不触发问题_技术教程

本文详解 xdebug 3 在 mamp 环境中与 vscode 调试失效的常见原因，重点对比 xdebug 2/3 配置差异，提供可验证的 php.ini、launch.json 配置方案，并推荐使用 xdebug_info() 快速诊断连接状态。

你遇到的“Xdebug 完全不触发断点”问题，极大概率源于 Xdebug 版本升级至 3.x 后配置项全面变更——而你的 php.ini 仍沿用 Xdebug 2 的旧参数（如 xdebug.remote_enable），这些参数在 Xdebug 3 中已被弃用或重命名，导致扩展虽加载成功，但调试功能完全未启用。

✅ 正确配置 Xdebug 3（适用于 MAMP + VSCode）

首先确认 Xdebug 版本：在终端执行

/Applications/MAMP/bin/php/php7.4.21/bin/php -v | grep -i xdebug

若输出含 Xdebug v3.x.x，请立即更新 php.ini（MAMP 对应 PHP 版本的 conf/php.ini）：

[xdebug]
zend_extension="/Applications/MAMP/bin/php/php7.4.21/lib/php/extensions/no-debug-non-zts-20190902/xdebug.so"
; ✅ Xdebug 3 核心配置（替代全部 remote_* 旧参数）
xdebug.mode = debug
xdebug.start_with_request = trigger  ; 或设为 'yes' 强制每次请求启动
xdebug.client_host = localhost
xdebug.client_port = 9003            ; 必须与 launch.json 中 port 一致
xdebug.log = "/Applications/MAMP/logs/xdebug.log"  ; 强烈建议开启日志排查

⚠️ 注意：xdebug.remote_* 系列参数（如 remote_enable, remote_host）在 Xdebug 3 中完全无效，保留它们将导致静默失败。

✅ VSCode launch.json 关键修正

你的配置中存在两个关键冲突点：

Listen for Xdebug 的 port: 9003 与 Launch currently open script 的 env.XDEBUG_CONFIG 中 ${port} 不匹配（后者未显式指定 port，默认为 0）；
XDEBUG_MODE 和 -dxdebug.mode 混用易引发覆盖。

推荐精简可靠的配置（仅保留最常用两项）：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/Applications/MAMP/htdocs/": "${workspaceFolder}/"
            }
        },
        {
            "name": "Launch current script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9003,
            "env": {
                "XDEBUG_MODE": "debug",
                "XDEBUG_SESSION": "1"
            }
        }
    ]
}

? 要点说明：

pathMappings 是 MAMP 必填项：将服务器路径 /Applications/MAMP/htdocs/ 映射到本地工作区，否则 VSCode 无法定位源码；

所有配置统一使用 port: 9003（Xdebug 3 默认端口），避免端口不一致；

移除 runtimeArgs 中的 -dxdebug.*，全部交由 php.ini 或 env 控制，减少冲突。

✅ 快速诊断：用 xdebug_info() 定位问题

在任意 PHP 文件（如 test.php）顶部添加：

用浏览器访问 http://localhost:8888/test.php（MAMP 默认端口），页面将显示：

✅ Xdebug enabled：确认扩展已加载；
✅ Mode: debug：确认调试模式激活；
✅ Client host/port: 显示连接目标（应为 localhost:9003）；
❌ 若出现 Connection failed: Connection refused，检查 VSCode 是否已启动 Listen for Xdebug；
❌ 若显示 No debugging client found，检查 client_host 是否为 localhost（非 127.0.0.1，尤其 macOS 可能有 hosts 解析差异）。