升级PhpStorm后Xdebug无法触发断点，寻求技术解决方法

（适配Apple Silicon + Local WP 6.4.2环境）

环境背景 #

• macOS 12.5（Apple Silicon）
• Local WP 6.4.2
• PhpStorm 2022.2（曾回滚至2022.1.3仍未解决）
• Xdebug 3.1.5

1. 校验Xdebug核心配置 #

在Local WP中打开站点的「Site Shell」，执行php -i | grep xdebug，确认以下关键参数：

• xdebug.mode = debug：必须开启调试模式
• xdebug.client_host = host.docker.internal：Apple Silicon环境下，Local WP基于Docker运行，需用此域名指向宿主机，避免IP映射问题
• xdebug.client_port = 9003：Xdebug 3默认端口，需与PhpStorm配置一致
• xdebug.start_with_request = yes：确保请求触发时自动发起调试连接
• xdebug.discover_client_host = 0：关闭自动发现，强制使用指定的client_host

若参数不符，进入站点「Settings」→「PHP」→「Edit php.ini」手动修改，重启站点后再次验证。

2. 核对PhpStorm调试配置 #

• 端口与监听设置：打开「Settings/Preferences」→「Languages & Frameworks」→「PHP」→「Debug」，确认「Xdebug」标签下的「Debug port」为9003，勾选「Can accept external connections」，并确保右上角的调试监听按钮（电话图标）处于激活状态。
• 服务器路径映射：进入「Settings/Preferences」→「Languages & Frameworks」→「PHP」→「Servers」，创建/编辑对应站点的配置：
  • 「Name」与Local WP站点域名完全一致（如test.local）
  • 「Host」填站点域名，「Port」设为80或443（根据HTTPS状态）
  • 勾选「Use path mappings」，将本地项目根目录映射到容器内路径（Local WP容器内默认路径为/app/public，可通过Site Shell的pwd命令确认）

3. 排查Apple Silicon架构兼容性 #

• 验证PHP架构：在Site Shell执行php -v，输出需包含aarch64（ARM原生编译），若显示x86_64则说明是转译版本，需在Local WP中切换为ARM原生的PHP版本。
• 验证Xdebug架构：执行php -i | grep xdebug.build_id，确认扩展为ARM64版本，若不匹配，可从Xdebug官网下载对应PHP版本的ARM64扩展，替换Local WP站点conf.d/php/xdebug.ini中指定的扩展路径。

4. 测试容器与宿主机的连通性 #

在Site Shell执行nc -zv host.docker.internal 9003，测试容器能否访问宿主机的9003端口：

• 若连接失败，检查macOS防火墙：打开「系统偏好设置」→「安全性与隐私」→「防火墙」→「防火墙选项」，确保PhpStorm被允许接收传入连接。

5. 重置PhpStorm调试缓存 #

关闭PhpStorm，删除对应版本的缓存目录：

• 2022.2版本：~/Library/Caches/JetBrains/PhpStorm2022.2
• 2022.1.3版本：~/Library/Caches/JetBrains/PhpStorm2022.1
  重启PhpStorm后重新配置调试参数。

6. 重置Local WP的Xdebug扩展 #

进入Local WP站点的「Settings」→「Add-ons」，禁用并重新启用Xdebug扩展，重启站点后再次测试断点。

内容的提问来源于stack exchange，提问作者Jaafar Abazid