能调试，但必须绕开 Composer install 的自动加载链路；根本原因是 Xdebug 仅对 composer.phar 入口生效，不延续至后续 require 加载的本地包文件，且 symlink 路径、autoload 优化或 IDE pathMappings 错配均导致断点失效。
能调试，但必须绕开 composer install 的自动加载链路——Xdebug 断点进不去本地包代码，根本原因不是配置错，而是 PHP 进程生命周期和 autoload 时机不匹配。
为什么 composer install 里设断点完全无效
Composer 执行安装时，composer.phar 是唯一 CLI 入口，Xdebug 只对它生效；后续所有 require 加载的本地包文件（比如 src/Helper.php）都发生在 autoload 阶段，此时 Xdebug 的请求级启动早已结束。即使开了 xdebug.start_with_request=yes，它也不会延续到动态 require 的路径里。
常见错误现象：
- 在本地包 PHP 文件里打的断点从不触发
- IDE 显示 “Breakpoint ignored: no executable code found”
-
vendor/下是符号链接，但断点指向的是 symlink 目标路径，而 IDE 实际监听的是 vendor 子目录
用最小脚本手动 require 本地包才是正解
跳过 Composer 安装流程，直奔你要验证的逻辑。前提是本地包已通过 path 仓库配置并成功 composer update，vendor/ 下已有符号链接。
在项目根目录新建 debug-local.php：
require 'vendor/autoload.php'; $helper = new MyCompanyUtilsHelper(); $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必须指向你真实编辑的本地包目录（例如/Users/me/projects/my-local-package），不是vendor/mycompany/utils - 不要依赖 IDE 的 “Run composer command” 按钮——它常默认关闭 Xdebug 或忽略 client 配置
path 仓库配置必须满足的硬性条件
这是断点能映射的前提，90% 的失败源于这里不合规。
主项目 composer.json 中的 repositories 块必须写成：
"repositories": [
{
"type": "path",
"url": "../my-local-package"
}
]
同时 require 中的包名必须与本地包 composer.json 中的 name 字段**逐字一致**（大小写、短横线、vendor 名全对齐）。
容易踩的坑：
- 路径末尾加了
/（"url": "../my-local-package/"→ 静默失效） - 本地包
composer.json缺"options": {"symlink": true}→ Windows/Docker 下 fallback 成 copy，改代码不生效 - Windows 用户没以管理员身份运行终端 → symlink 创建失败且无提示
- 本地包根目录下没有合法
composer.json（语法错误、尾逗号、单引号）→composer show --all根本不列出该包
调试 post-install-cmd 类钩子要绕开 IDE 拦截
这类脚本由 Composer 在生命周期中调用，可以被 Xdebug 捕获，但 IDE 内置的执行器常主动禁用调试。
正确做法是手动执行命令：
php -dxdebug.mode=debug -dxdebug.start_with_request=yes -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003 composer run-script post-install-cmd
注意：
-
composer.json中脚本定义必须指向可实例化类方法，例如："post-install-cmd": ["My\Scripts\Installer::onInstall"] - 避免用
composer dump-autoload -o→ 优化后类路径写死在autoload_classmap.php，IDE 无法关联源码 - 如果用了 symlink，改完本地包代码后无需重跑
composer update，但需确认ls -la vendor/vendor/name确实是箭头（Linux/macOS）或 JUNCTION（Windows）
最隐蔽的问题永远在路径映射：IDE 认为的“源码位置”和 Xdebug 实际加载的“文件磁盘路径”不一致，哪怕只差一个 ../，断点就彻底失联。
