必须将repositories写在主项目composer.json根级且与require同级，url用相对路径如"../my-local-package"并配"options":{"symlink":true}；本地包需name逐字匹配、version设"dev-main"、composer.json合法、Windows需管理员权限。
直接用 path 仓库 + symlink 是最可控、可复现的本地调试方式，不需要改全局配置，也不依赖 Git 分支名推断。
怎么配 repositories 才生效
必须写在主项目 composer.json 的根层级，和 require 平级，不能嵌套在 config 或 extra 里。常见无效写法包括：
- 把
repositories塞进本地包自己的composer.json—— 主项目完全无视 -
url写成/home/user/pkg或file://...—— Composer 静默跳过 -
url以斜杠结尾，比如"../my-pkg/"—— 解析失败，不报错但不加载
正确示例：
{
"repositories": [
{
"type": "path",
"url": "../my-local-package",
"options": {
"symlink": true
}
}
],
"require": {
"acme/utils": "*"
}
}
本地包 composer.json 要满足什么条件
不是“有就行”，而是四个硬性要求同时满足才能被识别：
-
name字段必须和require中的包名**逐字节一致**（大小写、分隔符、vendor 名全敏感） -
version推荐显式写成"dev-main"，避免依赖 Git 分支推断失败 - 目录下必须存在合法
composer.json文件（无语法错误、无尾逗号、全双引号） - Windows 用户需确保终端以管理员身份运行，否则
symlink创建会静默失败
验证方式：在主项目根目录执行 ls -la ../my-local-package/composer.json（Linux/macOS）或 dir ..\my-local-package\composer.json（Windows）。
为什么改了代码 vendor 里没变
因为 path 类型仓库默认只在 composer update 时建立链接，不会监听文件变化。常见误解：
- 以为
composer dump-autoload能刷新 symlink —— 它只重生成自动加载映射，不重建链接 - 删掉
vendor/后跑composer install—— 这会让 Composer 复制而非链接，失去调试意义 - 改完本地包代码后不触发
composer update acme/utils—— symlink 指向的仍是旧快照
正确做法：每次改完本地包源码，回到主项目执行：
composer update acme/utils
然后进 vendor/acme/utils 看是否为软链接（ls -l 显示 ->），以及修改时间是否同步。
调试时断点不命中怎么办
Xdebug 不会自动跟踪 symlink 后的物理路径，IDE 默认按 vendor/ 下的路径找源码。关键要对齐三处路径：
- IDE 的
pathMappings必须指向你实际编辑的本地包目录（如../my-local-package），不是vendor/acme/utils - 不要用 IDE 自带的 “Run composer command” 按钮调试钩子脚本 —— 它常禁用 Xdebug
- 手动运行调试脚本时，加完整参数：
php -dxdebug.mode=debug -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003 debug-local.php
最稳妥的调试入口是独立 PHP 脚本，直 require vendor/autoload.php 后调用本地包逻辑，绕开 Composer 生命周期干扰。
