17370845950

本文详解 xdebug 3 在 mamp 环境下与 vscode 调试失效的常见原因，重点对比 xdebug 2/3 配置差异，提供可验证的 php.ini、launch.json 配置及诊断方法（如 xdebug_info()），助你快速恢复断点调试功能。

你遇到的“Xdebug 完全不命中任何断点”问题，极大概率源于 Xdebug 版本升级导致的配置不兼容——尤其是从 Xdebug 2 升级到 Xdebug 3 后，几乎所有关键配置项名称和语义均已变更。你的 php.ini 中仍使用 xdebug.remote_* 等旧参数（如 xdebug.remote_enable=1），而 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（路径通常为 /Applications/MAMP/bin/php/php7.4.21/conf/php.ini）：

[xdebug]
zend_extension="/Applications/MAMP/bin/php/php7.4.21/lib/php/extensions/no-debug-non-zts-20190902/xdebug.so"
; ✅ 启用调试模式（替代旧版 remote_enable）
xdebug.mode = debug
; ✅ 自动启动调试会话（替代 remote_autostart）
xdebug.start_with_request = yes
; ✅ 指定 IDE 连接地址（替代 remote_host）
xdebug.client_host = localhost
; ✅ 设置客户端端口（VSCode 默认监听 9003，非 9000！）
xdebug.client_port = 9003
; ✅ 强制启用单步调试（推荐开启）
xdebug.step_into = 1
; ✅ 可选：启用函数调用追踪（调试时更清晰）
xdebug.show_local_vars = 1

⚠️ 关键变更说明： xdebug.remote_* → 全部废弃，改用 xdebug.client_* 和 xdebug.mode； xdebug.remote_port → 改为 xdebug.client_port； xdebug.remote_autostart=1 → 改为 xdebug.start_with_request=yes； xdebug.remote_enable=1 → 由 xdebug.mode = debug 替代（mode 支持多值，如 "debug,develop"）。

✅ VSCode launch.json 配置优化

你的 launch.json 中存在两处隐患：

1. Listen for Xdebug 配置的 "port": 9003 正确，但需确保 VSCode 的 PHP Debug 扩展已启用且未被其他进程占用该端口；
2. Launch currently open script 配置中混用了旧版环境变量（XDEBUG_CONFIG）和新版参数（xdebug.start_with_request），易引发冲突。

推荐精简为以下可靠配置（仅保留最常用场景）：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/Applications/MAMP/htdocs": "${workspaceFolder}"
      }
    }
  ]
}

? pathMappings 是关键！MAMP 默认将项目放在 /Applications/MAMP/htdocs/，而 VSCode 工作区路径可能不同，必须显式映射，否则断点路径无法匹配。

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

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

通过 MAMP 访问 http://localhost:8888/test.php，页面将显示完整 Xdebug 状态报告。重点关注：

• "Enabled"：是否为 true（若为 false，说明扩展未生效或配置错误）；
• "Mode"：是否包含 debug；
• "Client host" / "Client port"：是否与 VSCode 配置一致；
• "Connection status"：若显示 failed to connect，检查防火墙、端口占用或 client_host 是否应设为 host.docker.internal（Docker 环境）。

✅ 最后检查清单

• ✅ 重启 MAMP（必须重启 Apache/PHP 服务，而非仅刷新页面）；
• ✅ 在 VSCode 中点击「运行 → 启动调试」，确保左下角状态栏显示「Xdebug 正在监听 9003 端口」；
• ✅ 浏览器访问 URL 时，在地址栏末尾手动添加 ?XDEBUG_SESSION_START=1（或安装 Xdebug Helper 浏览器插件）；
• ✅ 终端执行 lsof -i :9003 确认端口未被其他进程占用。

完成上述步骤后，断点应能稳定触发。Xdebug 3 的设计更安全、更模块化，但迁移时务必以官方升级指南为唯一权威参考——切勿沿用 Xdebug 2 的思维配置。