PhpStorm 调试 WordPress 需三处 Xdebug 配置对齐：xdebug.mode=debug,develop、xdebug.client_host 与 IDE 中 Web Server Debug Validation 一致、xdebug.start_with_request=yes；并安装 WordPress 插件、标记 Resources Root、指定 WordPress 核心路径；用 Evaluate Expression 替代 var_dump；关闭 opcache。
能直接断点进 add_action 回调、看到 get_posts() 实际返回的数据结构、在主题 functions.php 里改一行就立刻生效——这些不是理想状态，而是 PhpStorm 配合正确配置后每天都在发生的事实。关键不在“能不能”，而在“哪几处配置错了会导致整个调试链路静默失败”。
为什么 Xdebug 断点不触发？检查这三处硬性匹配
断点灰色不可用、请求没进 IDE、控制台无任何调试日志——90% 是以下三个值没对齐：
-
xdebug.mode必须包含debug（不是仅develop），PHP 8.0+ 的写法是xdebug.mode = debug,develop -
xdebug.client_host和 PhpStorm 中的Debug → Web Server Debug Validation测试结果必须一致；本地 WAMP/XAMPP 常见填127.0.0.1，但 Docker 或 WSL2 环境下得填宿主机网关 IP（如172.28.0.1） -
xdebug.start_with_request推荐设为yes，避免手动加?XDEBUG_SESSION_START=1参数；若设为trigger，则必须配合浏览器插件或curl -H "Cookie: XDEBUG_SESSION=PHPSTORM"
别信 phpinfo() 里显示的 xdebug 模块已加载就万事大吉——xdebug_info() 页面底部的 “Debugger” 小节才告诉你它是否真在监听。
WordPress 插件回调函数无法跳转到定义？补全挂钩索引失效
PhpStorm 默认不会自动识别你写的 add_action('wp_enqueue_scripts', 'my_enqueue_handler') 中的 my_enqueue_handler，除非它知道这个函数是被 WordPress 挂钩系统注册的。
立即学习“PHP免费学习笔记（深入）”；
- 确保已安装 JetBrains 官方
WordPress插件，并重启 IDE - 在项目根目录右键 →
Mark Directory as → Resources Root，否则插件无法扫描到wp-content/plugins/下的自定义代码 - 进入
Settings → Languages & Frameworks → PHP → WordPress，手动指定 WordPress 核心路径（指向你本地wp-includes所在目录），否则do_action()调用点无法反向索引到你的add_action()
常见现象：光标放在 wp_head 上按 Ctrl+B 跳不到任何地方——说明核心路径未识别，挂钩索引根本没建起来。
主题开发时 var_dump() 输出乱码且不中断执行？用 Xdebug 的 Evaluate Expression 替代
在 header.php 或 functions.php 里写 var_dump($post)，不仅页面崩、中文变问号，还绕过断点逻辑。这不是代码问题，是输出通道错位。
- 把断点打在你想 inspect 的变量行（比如
$args = array(...);后面），然后右键 →Evaluate Expression（快捷键Alt+F8） - 在弹窗里直接输入
$args或get_queried_object()，回车即可看到完整结构化数据，支持展开、搜索、复制 JSON - 如果要查看全局对象（如
$wp_query），先确认当前作用域是否可访问；若提示Unresolved variable，说明该变量未在当前栈帧中初始化，需上移断点位置
注意：Evaluate Expression 本质是运行时求值，它比 var_dump 更接近真实执行流，且不会污染 HTTP 响应头或 HTML 结构。
修改插件后刷新页面没变化？检查 PhpStorm 的部署与符号链接行为
你以为改了 wp-content/plugins/my-plugin/my-plugin.php，但服务器实际加载的是 /var/www/html/wp-content/plugins/my-plugin 下的 symlink 目标文件——而 PhpStorm 默认同步的是源目录，不是链接目标。
- 在
Settings → Build, Execution, Deployment → Console → Terminal中，勾选Shell path并设为系统 shell（如bash），确保终端命令能正确解析符号链接 - 右键点击项目中任意插件目录 →
Deployment → Upload to …，确认上传路径是否指向真实 Web 根目录；若用 Docker，路径可能是/var/www/html/…，而非你本地的D:\wamp\www\… - 临时关闭
Settings → Appearance & Behavior → System Settings → Synchronize files on frame activation，防止 IDE 自动覆盖你刚手动改过的文件
最隐蔽的坑：WAMP/XAMPP 默认启用 opcache，即使你改了文件，PHP 还在用内存里的旧 opcode——务必在 php.ini 中设 opcache.enable=0 并重启 Apache，调试阶段别省这一步。
