断点不命中主因是Xdebug路径映射未对齐真实磁盘路径及IDE索引不同步：需手动配置Path Mappings、验证symlink是否生效、强制Reload项目并取消vendor目录Excluded标记。

断点不命中？先确认 Xdebug 路径映射是否对齐真实磁盘路径

本地 path 仓库（type: "path"）启用 symlink 后，Xdebug 断点常失效——不是 Xdebug 没启，而是 IDE 认为“这个文件不在项目里”。PHPStorm 的调试器依据文件系统路径匹配断点，而 symlink 目标路径若与 IDE 索引路径不一致（比如 Windows 上 C:\Users\me\pkg 和 IDE 显示的 //wsl.localhost/ubuntu/home/me/pkg），断点就永远不触发。

必须手动校准：打开 Run → Edit Configurations → PHP Remote Debug，在 Server configuration 区域点击 ... → Path Mappings，把本地包的真实绝对路径（如 C:\dev\my-utils）映射到容器或远程服务器上对应的路径（如 /var/www/my-utils）。Windows 用户尤其注意：不要用 WSL 路径别名，填物理盘符路径；macOS/Linux 用户检查是否用了 ~/，应展开为完整路径（如 /Users/you/my-utils）。

为什么改了本地包代码，断点还在旧行？检查 symlink 是否真正生效

Path 仓库默认尝试创建符号链接，但失败时会静默 fallback 到 copy 模式。你改的是源码目录，而 Xdebug 加载的是 vendor/vendor/name 下的副本——断点当然打不进新逻辑。

• Linux/macOS：运行 ls -la vendor/vendor/name，看到 -> 符号才表示 symlink 成功
• Windows：运行 dir vendor\vendor\name，看到 JUNCTION 或 SymLink 字样才是真链接
• 若显示为普通文件夹，说明 fallback 成 copy，立刻检查本地包根目录下的 composer.json 是否包含 "options": {"symlink": true}
• Windows 必须以管理员身份运行终端执行 composer install；Docker 场景需加 --cap-add=SYS_ADMIN 并确保挂载方式支持 symlink

Composer autoload 更新后，Xdebug 仍找不到类？补全和断点依赖 IDE 索引同步

即使 composer dump-autoload -o 成功生成了优化后的 vendor/autoload.php，PHPStorm 也不会自动重载类映射。结果就是：类名能补全、new 不报错，但断点进不去——因为 IDE 不知道这个类该映射到哪个物理文件。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

立即学习“PHP免费学习笔记（深入）”；

必须手动触发索引更新：

• 右键项目根目录 → Reload project from composer.json（该菜单仅在识别到 composer.json 后出现）
• 或按快捷键 Ctrl+Alt+Y（Win/Linux） / Cmd+Alt+Y（macOS）
• 检查 Settings → PHP → Composer 是否勾选了 Synchronize IDE settings with composer.json
• 极端情况可执行 File → Invalidate Caches and Restart → Invalidate and Restart

vendor 目录被标记为 Excluded，断点直接消失

PHPStorm 把 vendor/ 标为 Excluded 后，不仅补全失效，Xdebug 也完全忽略该目录下所有文件——断点图标变灰、点击无反应、调试时跳过所有 vendor/ 内部调用。

这不是配置错误，是高频误操作：

• 右键 vendor/ → Mark Directory as → Excluded 是最常见原因
• 正确做法：右键 vendor/ → Mark Directory as → Not Excluded
• 再确认 Settings → PHP → Include paths 中已包含 vendor/autoload.php
• 若仍异常，可在 Terminal 手动运行 composer dump-autoload -o，再点一次 Reload

断点调试 path 仓库最隐蔽的陷阱，从来不是 Xdebug 配置本身，而是 IDE 对 symlink 路径的感知偏差和 autoload 映射的索引延迟——这两处不显式干预，就永远在“改了却没生效”的循环里打转。