断点灰色主因是pathMappings映射错误或xdebug.mode未设为debug；需精确匹配服务器插件路径与本地目录，如"/var/www/html/wp-content/plugins/myplugin":"${workspaceFolder}"，并确保xdebug.mode=debug且重启调试会话。
断点灰色？先查 pathMappings 和 xdebug.mode
VSCode 里插件断点不生效，90% 是这两处配错。WordPress 插件文件被动态 include，VSCode 必须靠 pathMappings 把服务器上真实执行路径和你本地项目目录一对一映射上，否则根本找不到源码。
- 假设插件在容器内路径是
/var/www/html/wp-content/plugins/myplugin，你本地开的是~/projects/myplugin，launch.json 中就得写："\/var\/www\/html\/wp-content\/plugins\/myplugin": "${workspaceFolder}" -
xdebug.mode必须显式设为debug（Xdebug 3+ 不再认xdebug.remote_enable）；若还想看错误堆栈，可设成debug,develop - 改完后必须停掉当前调试会话再重启，不是刷新浏览器页面
xdebug.start_with_request=yes 才能进 admin-ajax.php 和 REST 接口
WordPress 后台、AJAX 请求、REST 路由（比如 /wp-json/wp/v2/posts）默认不带 XDEBUG_SESSION_START 参数，xdebug.start_with_request=trigger 或 yes 是唯一可靠方式——尤其当你用 Local、Docker 或 nginx 反向代理时，XDEBUG_* 头常被过滤掉。
- 开发机建议直接设
xdebug.start_with_request=yes，省去手动加 Cookie 或参数的麻烦 - 生产环境严禁开启，仅限本地调试
- WP-CLI 调试需额外加环境变量：
XDEBUG_MODE=debug php wp-cli.phar plugin activate myplugin
确认 PHP 加载的是你改的那个 php.ini
常见陷阱：你在编辑器里打开的 php.ini 根本没被 PHP 加载。Windows 下路径含空格（如 C:\Program Files\php）会导致 Xdebug 直接加载失败，日志里只显示 Failed loading xdebug。
- 终端执行
php --ini查看实际加载的配置路径，再用php -v确认 Xdebug 是否在输出里 - 执行
php --ri xdebug，输出中必须有Mode => debug，不能是off或空白 - 路径太长或含空格？把 PHP 和 Xdebug 挪到短路径下重装，例如
C:\php
插件入口文件必须带正确 DOCBLOCK 声明
VSCode 调试本身不依赖这个，但 WordPress 不识别插件，你就没法触发它的任何钩子逻辑——断点打在 add_action 或 register_activation_hook 里也白搭。
- 主文件（如
wp-content/plugins/myplugin/myplugin.php）开头必须有至少Plugin Name的注释块 - 确保文件名和目录名一致（
myplugin/目录下主文件必须叫myplugin.php） - 启用插件后，检查 WP 后台「已启用」列表里是否出现它；没出现就别调了，先解决识别问题
