path仓库必须写在项目根composer.json的repositories顶层数组中，type为"path"，url用相对路径指向含合法composer.json的本地包目录，且本地包name须与require完全一致；否则静默失效。
path仓库必须写在项目根composer.json的repositories顶层数组中
不是写在本地包自己的composer.json里，也不是塞进require或config字段下——它只在主项目根目录的composer.json顶层repositories数组中才生效。写错位置等于没写。
常见错误：把repositories复制进本地包的composer.json，结果主项目完全无视，还纳闷为什么composer install还在从 Packagist 下载。
正确结构示例：
{
"require": {
"myvendor/mypkg": "dev-main"
},
"repositories": [
{
"type": "path",
"url": "../mypkg"
}
]
}
-
url必须是相对路径（如../mypkg或./packages/mypkg），不能以/开头，也不能用file://或环境变量（~/mypkg、$HOME/mypkg均无效） -
repositories必须是数组，哪怕只有一个项，也要写成[{...}] - Windows 下路径分隔符统一用正斜杠
/，别用反斜杠（否则可能被忽略）
本地包的composer.json必须合法且name严格匹配
Composer 对name字段大小写、连字符、vendor 名完全敏感。主项目require里写的"myvendor/mypkg"，必须和本地包composer.json中的"name": "myvendor/mypkg"逐字一致，差一个字母或大小写都会报Could not find package。
另外，本地包目录下必须存在语法合法的composer.json，且至少含name字段；缺字段、JSON 格式错误、或name为空，Composer 都会静默跳过该仓库，不报错也不提示。
- 若本地包尚未初始化 Git，建议显式加
"version": "dev-main"，否则 Composer 可能无法推断分支版本 - 推荐在本地包
composer.json中设"minimum-stability": "dev"和"prefer-stable": false，避免因稳定性约束被跳过 - 不要在
require里写"*"或"^1.0"——这些会绕过path源，退回到 Packagist 查找
执行composer install而非update才能重建symlink
已有composer.lock时，composer update只会更新锁文件中已记录的源，不会重新识别新配置的path仓库。必须删掉composer.lock和vendor/后运行composer install，才会真正走path流程并创建符号链接（Linux/macOS）或目录映射（Windows）。
验证是否生效：
- Linux/macOS 执行：
readlink vendor/myvendor/mypkg，应输出指向本地包路径 - Windows 执行：
dir vendormyvendormypkg，若显示“符号链接”或“联机”字样，说明是映射；若只是普通目录，则 fallback 到了 copy 模式（常因权限不足导致） - 运行：
php -r "echo class_exists('MyVendor\MyPkg\Helper') ? 'ok' : 'fail';"，输出ok才说明 autoload 生效
改了本地包代码，主项目没变化？检查symlink和autoload-dev
符号链接本身不会自动更新，但只要链接存在，修改本地包代码就会实时反映到主项目。如果没生效，大概率是链接根本没建成功，或者 autoload 配置没对上。
重点排查：
- 确认
vendor/myvendor/mypkg是链接（非真实目录）；若不是，说明上次install没走path流程 - 本地包
composer.json中autoload或autoload-dev的 PSR-4 映射，末尾必须带双反斜杠："MyVendor\MyPkg\": "src/"，写成"MyVendor\MyPkg": "src/"就失效 - 改完
autoload后，必须手动运行composer dump-autoload --dev（尤其测试类在autoload-dev里时） - Windows 下若未以管理员身份运行终端，或系统禁用了符号链接策略，Composer 会 fallback 到 copy 模式——此时改本地包毫无意义
最易被忽略的是：path仅用于开发联调，严禁进入生产环境；服务器上路径不存在，composer install会直接失败，不会降级或提示。
