Xdebug连接失败主因是版本不匹配或xdebug.mode配置错误；需确认PHP/Xdebug版本、检查php.ini路径映射、启用xdebug.mode=debug及路径映射，CLI调试需加XDEBUG_MODE=debug环境变量。
PhpStorm 连不上 Xdebug 怎么办
绝大多数连接失败不是因为配置错，而是因为 Xdebug 版本与 PHP 版本不匹配，或 xdebug.mode 没设对。PHP 8.0+ 默认用 xdebug.mode=debug，旧版（如 Xdebug 2）则靠 xdebug.remote_enable=1，混用会静默失效。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 运行
php -v和php -m | grep xdebug确认 Xdebug 是否加载、版本号（如Xdebug v3.1.5） - 查
php --ini找到生效的php.ini，检查是否有两份 Xdebug 配置（比如同时存在xdebug.so和xdebug.dll加载，或 .ini 文件被重复包含） - Xdebug 3 必须显式开启调试模式：
xdebug.mode=debug，并配xdebug.start_with_request=yes或触发断点时加XDEBUG_SESSION_START=1GET 参数 - Windows 下注意路径分隔符：
xdebug.log="C:\temp\xdebug.log"要用双反斜杠或正斜杠，否则日志不生成
PhpStorm 中断点不命中常见原因
断点灰掉、点击无反应，往往不是代码问题，而是路径映射没对齐。PhpStorm 依赖「本地文件路径」和「服务器上实际运行路径」的精确映射，哪怕多一个 / 或大小写差异都会失败。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 在 PhpStorm 的
Preferences > PHP > Servers里，确认已添加对应服务器，并勾选Use path mappings - 映射关系必须一对一：
/var/www/html/→~/Projects/myapp/，不能写成/var/www/html（少末尾斜杠）或~/Projects/myapp（Mac/Linux 大小写敏感，别用MyApp） - 如果用 Docker，宿主机路径要填容器外的真实路径（如
/Users/xxx/myapp），容器内路径填/var/www/html，别填http://localhost这类 URL - 启用
xdebug.log后，查看日志里Resolved path行，它会告诉你 PhpStorm 实际收到的请求路径是什么，比猜更可靠
如何让 CLI 脚本也能被 PhpStorm 断点调试
Web 请求调试通了，但跑 php artisan command 或 php script.php 就进不了断点？默认 CLI 模式下 Xdebug 不自动启动，且 PhpStorm 的 CLI 调试需要额外激活。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- CLI 启动时必须带环境变量：
XDEBUG_MODE=debug php script.php（Xdebug 3）或export XDEBUG_CONFIG="idekey=PHPSTORM"+php -d xdebug.remote_enable=1 script.php（Xdebug 2） - PhpStorm 中，右键脚本 →
Debug 'script.php'，它会自动注入环境变量；但如果手动执行命令，就得自己加 - 确保 CLI 使用的
php.ini和 Web 使用的是同一份（php --ini对比），常见坑是 CLI 用系统默认 ini，Web 用 MAMP/XAMPP 自带的 - 如果用 Composer 脚本（如
composer run dev），需在composer.json的 scripts 里显式加XDEBUG_MODE=debug前缀
调试时变量显示为 __set_state 或一堆 protected 字段
这不是 bug，是 Xdebug 的默认变量展开策略太保守。尤其 Laravel Eloquent 模型、Symfony Container 这类深度封装对象，直接展开会卡死或超内存。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 在 PhpStorm 的
Preferences > PHP > Debug > Xdebug中，调高Max. depth（默认 5，可设 10）、Max. children（默认 100，可设 200），避免截断 - 勾选
Enable 'Evaluate expressions' in debugger，然后在 Variables 面板右键变量 →View Text，能绕过结构化渲染，看到原始 var_export 输出 - 对 Laravel 模型，直接在 Debug Console 输入
$model->toArray()比展开 protected 属性更快更准 - 慎用
Max. array elements设过大（如 10000），会导致调试器响应变慢，尤其处理大数组或 JSON 解析结果时
路径映射和 Xdebug 模式开关是两个最常被跳过的步骤，其他都好调；但只要其中一个不对，整个调试链就断在看不见的地方。
