90%的xdebug调试失败源于pathmappings错配和xdebug.mode未设为debug；需确认php.ini中xdebug.mode=debug生效、重启php进程、精确配置pathmappings映射、启用xdebug.start_with_request=yes，并确保插件被wordpress正确识别并启用。

断点灰色、Xdebug不触发、插件钩子根本进不去——90% 的问题出在 pathMappings 和 xdebug.mode 配置错位，而不是代码或插件本身。

确保 xdebug.mode=debug 且生效

Xdebug 3+ 已废弃 xdebug.remote_enable，必须显式设为 debug（或 debug,develop）才能启用调试能力。仅靠 XDEBUG_SESSION_START Cookie 或参数无法激活断点。

• 检查 php.ini：确认有 xdebug.mode=debug（不是 off、develop 单独值，也不是注释掉的状态）
• 执行 php --ri xdebug，输出中必须出现 Mode => debug，否则配置未加载或被覆盖
• 改完后必须重启 PHP 进程（如 sudo service php8.2-fpm restart 或重启 Docker 容器），不是刷新浏览器

精确配置 launch.json 的 pathMappings

WordPress 插件常通过 include 或钩子动态加载，VSCode 必须知道“服务器上执行的文件路径”和“你本地打开的文件路径”之间的严格映射关系，否则找不到源码、断点永远灰色。

Cn Password Generator

安全的随机密码生成器。支持自定义长度、字符类型（大写/小写字母、数字、特殊符号），排除相似字符，批量生成。纯 Python 标准库，无需 API 密钥。

下载

• 用 php --ini 确认实际生效的 php.ini 路径，再查 Xdebug 是否启用；别编辑错文件（尤其 Windows 下 C:\Program Files\php\php.ini 因空格常导致 Xdebug 加载失败）
• 假设插件在服务器上真实路径是 /var/www/html/wp-content/plugins/myplugin，而你本地 VSCode 打开的是 ~/projects/myplugin，则 pathMappings 必须写成：
  "\/var\/www\/html\/wp-content\/plugins\/myplugin": "${workspaceFolder}"
• 路径中的斜杠要转义（\/），Windows 用户注意正反斜杠统一用 /，不要混用 \

让 AJAX、REST、后台请求自动进调试

WordPress 后台页面、admin-ajax.php、/wp-json/ 接口默认不带调试触发参数，浏览器加 ?XDEBUG_SESSION_START=1 很麻烦，且容易被 nginx / proxy 过滤掉。

• 在 php.ini 中设 xdebug.start_with_request=yes（开发机推荐），所有 HTTP 请求都会自动启动调试会话
• 若需更精细控制，可设 xdebug.start_with_request=trigger，然后手动加 Cookie XDEBUG_SESSION=PHPSTORM（VSCode 默认识别 PHPSTORM 或 VSCODE）
• 生产环境严禁开启此选项，仅限本地开发容器或 Local by Flywheel / Docker 环境

验证插件是否被 WordPress 正确识别

VSCode 断点能打，不代表 WordPress 会执行它——如果插件没被识别，add_action、register_activation_hook 根本不会注册，断点自然无效。

• 主文件（如 myplugin/myplugin.php）开头必须有 DOCBLOCK，至少含 Plugin Name: 行
• 目录名与主文件名必须一致：myplugin/ 目录下主文件必须叫 myplugin.php，不能是 index.php 或 main.php
• 在 WordPress 后台「插件」列表里能看到该插件名称，并能成功启用——这是断点能触发的前提

最容易被忽略的是：你以为改的是正在运行的那个 php.ini，其实 PHP 加载的是另一个；你以为断点打在 add_action 里就能停住，其实插件压根没被识别。先跑通「插件启用 → 钩子注册 → 请求触发」这条链，再调调试配置。