根本原因是Composer未将本地包源码视为执行入口,Xdebug仅在CLI入口(如composer.phar)触发,后续require的本地包文件不被跟踪;且symlink路径与IDE路径不一致、autoload优化、path mapping错误等加剧断点失效。

断点进不去本地包代码,根本原因不是Xdebug没开,而是Composer没把你的源码当“执行入口”——它只对composer.phar或你手动写的debug-local.php启用调试,后续require进来的本地包文件默认不被Xdebug跟踪。
为什么composer install和post-install-cmd脚本都断不进本地包
Composer 的 CLI 入口(如 composer.phar)启动时 Xdebug 会介入,但一旦进入依赖解析、下载、autoload 加载阶段,后续所有 require 或 include 的 PHP 文件(包括你本地包的 src/Helper.php)都在同一个进程里动态载入,xdebug.start_with_request=yes 不会重新触发断点监听。
- symlink 路径和 IDE 中打开的路径不一致:比如 IDE 显示的是
/Users/me/my-pkg/src,但 vendor 下软链指向的是/private/var/folders/xxx/my-pkg,断点直接失效 -
composer dump-autoload -o把类映射写死进vendor/composer/autoload_classmap.php,IDE 找不到原始文件位置 - IDE 的 path mapping 配错了目标目录:必须映射到你日常编辑的那个本地包根目录,不是 vendor 下的 symlink 目标路径(后者是只读副本或符号链接)
用最小脚本手动 require 才能稳稳断点
绕过 Composer 安装流程,直奔你要调试的逻辑。前提是本地包已通过 path 仓库配置好,且 vendor/ 下已有 symlink。
- 在项目根目录新建
debug-local.php:
require 'vendor/autoload.php'; $helper = new MyPackageHelper(); $helper->doSomething(); // ← 在这行设断点
- 终端执行(别用 IDE 的 “Run” 按钮):
php -dxdebug.mode=debug -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003 debug-local.php
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
- 确保 IDE 已开启 Xdebug 监听,并在 path mappings 中将
MyPackage命名空间映射到你本地编辑的包目录(例如../my-pkg),而不是vendor/my-vendor/my-pkg
联动测试:让 PHPUnit 也走本地源码路径
PHPUnit 默认加载 vendor/ 下的类,即使你改了本地包代码也不会生效——除非强制它从 symlink 目录加载。
- 确认
vendor/my-vendor/my-pkg是软链接(Linux/macOS)或真实映射(Windows),运行:readlink vendor/my-vendor/my-pkg或ls -l vendor/my-vendor/my-pkg - 在本地包的
composer.json中确保"autoload-dev"正确声明测试命名空间,例如:"autoload-dev": { "psr-4": { "MyPackage\Tests\": "tests/" } }(注意末尾反斜杠不能少) - 改完 autoload 后必须执行:
composer dump-autoload --dev,否则vendor/composer/autoload_dev.php不更新 - 跑测试时加
-d xdebug.mode=debug参数,和 debug-local.php 一样触发断点:php -dxdebug.mode=debug -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003 vendor/bin/phpunit
最易忽略的一点:Windows 用户若未以管理员身份运行终端,composer update 创建 symlink 会静默失败,vendor/ 下看到的是完整复制而非链接——此时改本地代码永远不生效,但错误日志里一个字都不会提。










