WP-CLI命令Xdebug不进断点需设XDEBUG_MODE=debug环境变量，因CLI不走HTTP协议，xdebug.start_with_request=yes对其无效；同时须确认CLI用的php.ini路径、pathMappings映射正确，并重启调试会话。
wp-cli命令里Xdebug不进断点？检查XDEBUG_MODE环境变量
WP-CLI默认不触发Xdebug，即使php.ini里写了xdebug.start_with_request=yes也没用。因为CLI请求不走HTTP协议，Xdebug 3必须靠环境变量激活调试模式。
正确做法是加XDEBUG_MODE=debug前缀运行命令：
env XDEBUG_MODE=debug wp plugin activate my-plugin
常见错误现象：断点全灰、Debug Console里没连接日志、VSCode底部状态栏不显示Xdebug listening。
- 别只改Apache或PHP-FPM的php.ini——CLI用的是另一套配置，执行
php --ini确认加载路径 - 如果用
wp-cli.phar，确保php wp-cli.phar调用的PHP和你IDE里配的CLI interpreter是同一个 - 某些CI或Docker环境会过滤
XDEBUG_*环境变量，此时只能改php.ini加xdebug.mode=debug,develop
主题/插件代码里断点不命中？重点核对pathMappings
VSCode或PhpStorm里断点变灰色，90%是pathMappings没配对。WordPress在容器或远程环境里路径（如/var/www/html）和你本地项目路径（如D:\projects\mywp）天然不一致。
在.vscode/launch.json中必须显式映射：
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
}
注意斜杠方向统一用/，Windows本地路径也别写\；如果插件单独放在wp-content/plugins/my-plugin外（比如用Composer装在vendor/），还得额外加一条映射。
- 配完后访问
http://your-site.test/xdebuginfo/（VVV）或phpinfo()页面确认xdebug.client_host和xdebug.client_port是否匹配VSCode监听端口 - 修改
launch.json后必须重启VSCode的调试会话，不是重载窗口 - 用
wp eval "echo WP_CONTENT_DIR;"验证WordPress实际路径，再和映射值比对
钩子函数里var_dump没输出？用WP_CLI::debug替代并选对logger组
在add_action('init', 'my_func')这类钩子里直接var_dump()，往往看不到结果——它被缓冲、被WordPress拦截、或输出到CLI stderr但被忽略。
WP-CLI提供更可靠的调试入口：WP_CLI::debug()，它把信息发到指定logger组，配合--debug参数就能看到：
function my_func() {
WP_CLI::debug( 'User ID: ' . get_current_user_id(), 'auth' );
}
add_action( 'init', 'my_func' );
运行wp rewrite structure '/%postname%' --debug，就能在debug组里看到那条日志。
- logger组名（第二个参数）要合理，比如
'db'用于数据库操作、'auth'用于登录相关，避免混用导致信息淹没 -
WP_CLI::debug()只在--debug开启时生效，生产环境不会输出 - 不要在
wp-config.php或wp-settings.php早期加载阶段调用，那时WP_CLI类还没加载
断点进了但变量值看不清？启用xdebug.var_display_max_depth
WordPress对象嵌套深（比如WP_Query、WP_Post），默认Xdebug只展开3层，$query->posts[0]->meta这种结构点不开。
在php.ini里加大两个关键参数：
xdebug.var_display_max_depth=10 xdebug.var_display_max_children=256
否则你看到的永远是object(WP_Post)#123 (24) { ... }，省略号里到底有啥得猜。
- 改完必须重启PHP服务（
sudo systemctl restart php8.1-fpm或net stop wampapache64 & net start wampapache64） - 如果用Docker，别只改宿主机php.ini——要进容器里改
/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini - 过度提高数值会影响调试器响应速度，开发机设到10够用，别设成-1
