直接composer install无法在本地包代码中断点，因Xdebug仅对CLI入口生效，不延续至后续require加载的本地包文件；且symlink路径不一致、优化autoload或IDE pathMappings错配均导致断点失效。
能调试，但必须绕开 Composer 自身脚本的自动触发机制，否则断点根本进不去。
为什么直接 composer install 不会停在本地包代码里
Composer 执行安装时，会先加载自身逻辑、解析依赖、下载/复制包，最后才执行 autoload 和用户代码。Xdebug 默认对 composer.phar 入口文件启用，但本地包的 PHP 文件（比如 src/Helper.php）是在后续 require 阶段才载入的——此时 Xdebug 的“自动启动”早已结束。
-
xdebug.start_with_request=yes只对当前 CLI 进程入口生效，不延续到后续动态require - 本地包若通过 symlink 加载（path repository），其文件路径可能和 IDE 中打开的路径不一致，导致断点失效
- 如果用了
composer dump-autoload -o，类被写进vendor/composer/autoload_classmap.php，实际执行的是优化后静态映射，IDE 无法关联源码
正确做法：用最小 PHP 脚本手动 require 本地包
跳过 Composer 安装流程，直奔你要调试的逻辑。前提是本地包已通过 path 仓库配置并 composer update 成功，且 vendor/ 下已存在符号链接或副本。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 在项目根目录下新建一个
debug-local.php：
require 'vendor/autoload.php'; // 假设本地包命名空间是 mycompany/utils，主类在 src/Processor.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）已开启监听，并且
pathMappings指向你本地包的真实磁盘路径（不是vendor/下的 symlink 目标，而是你编辑的那个目录）
调试 post-install-cmd 类脚本的特殊处理
这类脚本由 Composer 在安装/更新后调用，属于 Composer 生命周期钩子，可以被 Xdebug 捕获，但需显式启用且避开 IDE 的全局拦截陷阱。
- 在
composer.json中定义脚本时，确保指向的是可调试的类方法，例如："post-install-cmd": ["My\Scripts\Installer::onInstall"] - 不要依赖 IDE 内置的 “Run composer command” 按钮——它常自动加
-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 - 关键点：
xdebug.start_with_request=yes必须带上，否则钩子函数执行时 Xdebug 已关闭；同时确认你的php.ini里没全局设置xdebug.ignore=...把该脚本路径过滤掉了
Windows / Docker 下 symlink 失效导致断点找不到源码
这是最隐蔽的问题：你以为在本地包里设了断点，但实际运行的是 vendor/ 下的副本，而 IDE 加载的是 symlink 指向的原始目录——路径不匹配，断点灰色不可用。
- 验证是否真用了 symlink：
dir vendormycompanyutils（Windows）或ls -la vendor/mycompany/utils（Linux/macOS）；看到JUNCTION或->才算成功 - 若显示为普通文件夹，说明 fallback 到 copy 模式，此时必须去
vendor/目录里找对应文件设断点，或修复本地包的composer.json，加上："options": {"symlink": true} - Docker 中还需确保容器启动时加了
--cap-add=SYS_ADMIN，且挂载卷支持follow_symlinks - IDE 的
pathMappings必须严格匹配 symlink 的目标路径，不能写成./my-pkg，得写成/host/path/to/my-pkg（宿主机绝对路径）
真正卡住人的从来不是 Xdebug 配不配得上，而是断点设在哪、PHP 加载的是哪份文件、IDE 认出的是哪个路径——三者稍有错位，就变成“代码跑了，断点不动”的假死现场。
