本地 Composer 包无法用 composer install 断点调试，因 Xdebug 仅对 CLI 入口生效，不延续至 require 加载的本地包文件；需改用 path 仓库类型+符号链接，再通过独立 PHP 脚本手动 require 并启用 Xdebug 调试。
本地 Composer 包无法直接用 composer install 断点调试，因为 Xdebug 只对 CLI 入口生效，不延续到后续 require 加载的本地包文件。
为什么 composer install 里设不了断点
Composer 执行安装时，先跑自身逻辑、解析依赖、复制/链接包，最后才加载 autoload 并执行用户代码。Xdebug 的 xdebug.start_with_request=yes 只作用于 composer.phar 这个入口进程，而你的本地包（比如 src/Helper.php）是在 require 阶段动态载入的——此时调试会话早已结束。
常见错误现象包括：
- 在本地包 PHP 文件里设了断点，但运行
composer install完全不中断 - IDE 显示 “Breakpoint ignored” 或路径映射灰色不可用
- 断点位置实际是 vendor 下 symlink 目标路径，但 IDE 打开的是你编辑的源目录，两者不一致
用 path 仓库类型让本地包被实时识别
这是最可控、可复现的方式，适用于开发中频繁改本地包又想被主项目实时感知的场景。
操作步骤：
- 在主项目
composer.json顶部加repositories块，url必须是相对路径（如../my-local-package），不能用~/或绝对路径 - 确保目标目录下有合法的
composer.json（含name和autoload配置） - 把
require中的版本号换成分支别名，例如："vendor/my-local-package": "dev-main" - 运行
composer update vendor/my-local-package（必须带包名，否则可能误更新其他依赖）
完成后，vendor/vendor/my-local-package 会变成指向你本地目录的符号链接，且 autoload 正常注册。
手动 require + 启动独立调试会话
跳过 Composer 安装流程，直奔你要调试的逻辑。前提是本地包已通过 path 仓库配置并成功 composer update，vendor/ 下已有 symlink。
在项目根目录新建 debug-local.php：
require 'vendor/autoload.php'; $proc = new MyCompanyUtilsProcessor(); $proc->run(); // 在这行设断点
然后用带 Xdebug 的 PHP 直接运行：
php -dxdebug.mode=debug -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003 debug-local.php
关键检查点：
- IDE（PhpStorm / VS Code）已开启 “Listen for Xdebug connections”
-
pathMappings指向你本地编辑的包目录（不是vendor/下的 symlink 目标路径） - 没启用
composer dump-autoload -o，否则类被写进autoload_classmap.php，IDE 无法关联源码
调试 post-install-cmd 类脚本的注意事项
这类脚本由 Composer 在安装/更新后调用，属于生命周期钩子，可以被 Xdebug 捕获，但容易被 IDE 的“Run composer command”按钮干扰。
正确做法：
- 在
composer.json中定义明确的类方法，如："post-install-cmd": ["My\Scripts\Installer::onInstall"] - 不要依赖 IDE 内置按钮——它常自动加
-dxdebug.mode=off或忽略 client 配置 - 手动执行：
php -dxdebug.mode=debug -dxdebug.start_with_request=yes -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003 $(which composer) install
真正容易被忽略的是：断点必须设在脚本方法内部，而不是 composer.json 或命令行参数层面；且 IDE 的 pathMappings 要覆盖该脚本所在包的真实路径，而非 vendor symlink 路径。
