能调试，但必须绕开 Composer 自动触发流程；因 Xdebug 仅对 CLI 入口生效，本地包文件在后续 require 阶段才加载，此时 xdebug.start_with_request=yes 已失效，且 symlink 路径错配、autoload 优化或 IDE pathMappings 不一致均导致断点失败。
能调试，但必须绕开 composer install 和 post-install-cmd 的自动触发流程——否则 Xdebug 根本进不到本地包源码里。
为什么 composer install 无法断点进本地包
Xdebug 只对 CLI 入口文件（如 composer.phar）生效，而本地包的 PHP 文件（比如 src/Helper.php）是在后续 require 阶段才加载的。此时 Xdebug 的“请求级启动”早已结束，xdebug.start_with_request=yes 不会延续到动态引入的文件。
常见错误现象包括：
- 在 IDE 里对本地包代码打了断点，运行
composer install却完全不中断 - 改了本地包代码，
vendor/下对应文件没变——其实是被复制而非软链接 -
composer dump-autoload -o后类走的是vendor/composer/autoload_classmap.php，IDE 无法映射回源码
用最小脚本手动 require 本地包逻辑
跳过 Composer 安装流程，直奔你要验证的调用链。前提是本地包已通过 path 仓库配置并成功 composer update，vendor/ 下已有符号链接。
在项目根目录新建 debug-local.php：
require 'vendor/autoload.php'; $helper = new MyPackageHelper(); $helper->doSomething(); // 在这行设断点
然后用带 Xdebug 的 PHP 直接运行：
php -dxdebug.mode=debug -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003 debug-local.php
关键点：
- 确保 IDE（PhpStorm / VS Code）已开启 Xdebug 监听
-
pathMappings必须指向你真正编辑的本地包目录（如../my-package），不是vendor/my-vendor/my-package这个链接目标 - 不要依赖 IDE 的 “Run composer command” 按钮——它常默认禁用 Xdebug
repositories 配置不生效的硬性条件检查
哪怕只漏一个，composer update 就会静默 fallback 到 Packagist，且不报错。
必须同时满足：
-
repositories字段写在主项目composer.json根层级，和require同级 -
url是相对路径（如"../my-package"），不能以/或file://开头，也不能以/结尾 - 本地包目录下有合法
composer.json，且name字段与require中的包名逐字匹配（大小写、斜杠、连字符全敏感） - 显式启用 symlink：
"options": {"symlink": true}加在repositories条目里 - 本地包已初始化 Git 仓库；若无 Git，需在本地包
composer.json中显式写"version": "dev-main"
改了本地包代码却没生效？别删 vendor/ 重装
删 vendor/ + composer install 会把本地包完整复制进去，失去“改即生效”的意义。
正确做法是：
- 改完本地包代码后，运行
composer update my-vendor/my-package（推荐，精准刷新） - 或仅刷新 autoload：
composer dump-autoload（仅当类结构未变、只改逻辑时够用） - 验证是否真链接成功：
ls -l vendor/my-vendor/my-package（Linux/macOS）看是不是软链接；Windows 下用dir vendor\my-vendor\my-package - 快速确认 autoload 是否就位：
php -r "echo class_exists('MyPackage\Helper') ? 'ok' : 'fail';"
最常被忽略的是：IDE 的 pathMappings 指向了 vendor/ 下的链接路径，而不是你实际编辑的那个本地目录——断点永远进不去，你还以为是 Xdebug 没配好。
