IDE断点失效主因是pathMappings未映射本地真实路径：Xdebug加载symlink目标文件，而IDE默认在vendor路径设断点，路径不一致导致断点变空心圆；须在PhpStorm或VS Code中显式配置vendor包到本地绝对路径的映射。
IDE 的 pathMappings 必须指向本地包真实编辑路径，不是 vendor 下的 symlink 目标
断点失效最常见原因：IDE 认为你在调试 vendor/acme/utils/src/Helper.php，但你实际编辑的是 ../acme-utils/src/Helper.php。Xdebug 加载的是 symlink 指向的真实文件，但 IDE 默认把断点打在 vendor 路径上，两边路径对不上，断点就变空心圆。
解决方式不是改 symlink，而是显式告诉 IDE：“vendor/acme/utils 这个路径，在我机器上对应的是 /Users/me/dev/acme-utils”。
- PhpStorm：Preferences → PHP → Servers → 点击对应 server → 在 “Path mappings” 表格里添加映射：
vendor/acme/utils→/absolute/path/to/your/local/acme-utils - VS Code：在
.vscode/launch.json的pathMappings字段里写："vendor/acme/utils": "/absolute/path/to/your/local/acme-utils" - 绝对路径必须真实存在、可读，且不能是
~/或相对路径（如../acme-utils），IDE 不解析 shell 展开
composer.json 里启用 symlink 需要本地包自身声明 "options": {"symlink": true}
只在主项目 repositories 里写 "type": "path" 不够——Composer 默认会复制文件，而不是创建软链接。没有 symlink，你就没法实时改代码、立刻看到效果，调试就失去意义。
这个开关必须放在本地包自己的 composer.json 里，不是主项目的：
- 确认本地包根目录下
composer.json包含："options": {"symlink": true} - 主项目运行
composer update acme/utils（带包名）才会触发 symlink 创建 - 验证是否生效：
ls -la vendor/acme/utils应显示指向../acme-utils的链接，而不是普通目录 - Composer 2.2+ 才支持该配置；旧版本需升级或改用全局
composer config --global path.repo.symlink true
autoload 映射不更新会导致 new 类时直接报错，和断点无关但常被混淆
即使 symlink 成功了，new AcmeUtilsHelper() 仍可能报 Class not found。这不是断点问题，而是 autoloader 根本没把本地包的 src/ 目录加进映射表。
- 本地包的
composer.json必须有合法autoload块，例如："psr-4": {"Acme\Utils\": "src/"} - 主项目执行
composer dump-autoload（不是install或update）才能刷新自动加载规则 - 检查生成结果：
grep AcmeUtilsHelper vendor/composer/autoload_psr4.php，应看到对应路径条目 - 如果用了
classmap，它优先级低于psr-4，别让两者冲突覆盖
用最小脚本手动 require 启动调试，绕过 composer install 生命周期
composer install 本身不会执行你的本地包代码，Xdebug 只对入口进程生效，后续 require 的文件不会继承调试上下文。想在 Helper::doSomething() 里设断点，就得让那一行成为脚本的直接执行路径。
- 在主项目根目录新建
debug-helper.php：
require 'vendor/autoload.php'; $helper = new AcmeUtilsHelper(); $helper->doSomething(); // ← 在这行设断点
php -dxdebug.mode=debug -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003 debug-helper.php
pathMappings 已按第一条配好断点映射真正卡住的地方，往往不是配置漏了哪一项，而是三处路径没对齐：IDE 里打开的文件路径、Xdebug 实际加载的文件路径、autoload 查找类时用的路径。这三个值必须两两一致，少一个都白配。
