repositories必须位于主项目composer.json根级，仅读取顶层数组；url须指向含composer.json的目录而非文件；name大小写及分隔符严格匹配；path仓库需显式配置symlink并运行update生效。
repositories 必须写在主项目 composer.json 根级
Composer 只读取项目根目录下 composer.json 的顶层 repositories 数组，其他位置全无效。写进 config、extra 或本地包自己的 composer.json 里，等于没配。
常见错误现象是执行 composer install 后报 Could not find a matching version of package vendor/name，但实际原因不是网络问题，而是 repositories 根本没被加载。
-
repositories必须是数组，哪怕只配一个 path 源，也要写成[{"type":"path","url":"../my-pkg"}] -
url指向的是**含composer.json的目录**，不能是文件路径（如../my-pkg/composer.json） - 不支持
file://、~、环境变量（如$HOME），Windows 下绝对路径也容易静默失败，优先用相对路径
path 仓库的 url 和 name 必须严格对齐
Composer 对 name 字段做逐字匹配：大小写、vendor 名、分隔符（只认短横线 -）全部敏感。比如本地包 composer.json 里写 "name": "acme/utils"，你在主项目 require 中就必须写 "acme/utils": "dev-main"，写成 "Acme/utils" 或 "acme_utils" 都会失败。
- 本地包目录下必须存在合法的
composer.json，且至少包含name字段；version字段可写"dev-main"，但非必需 -
url是相对路径，必须能从主项目composer.json所在位置正确解析，例如主项目在/project，则"../my-utils"应指向/my-utils - 同名包只取
repositories数组中第一个匹配项，第二个同名的 path 仓库完全被忽略，无 fallback
启用 symlink 需要显式配置并运行 update
默认行为是复制（copy），改了本地代码，vendor/ 下不会自动更新。要让修改实时生效，必须启用符号链接，且靠 composer update vendor/name 触发重建，composer install 不会创建或刷新 symlink。
- 在主项目
composer.json的对应repositories条目里加"options": {"symlink": true}，例如：{"type":"path","url":"../my-utils","options":{"symlink":true}} - 或在本地包自己的
composer.json里加同样字段，效果等价 - Windows 用户需开启“开发者模式”或以管理员权限运行命令行，否则
symlink创建失败且无提示 - 验证是否成功：
ls -la vendor/acme/utils应显示箭头指向源目录；Windows 下用dir vendor\acme\utils看是否为“快捷方式”类型
多个 path 仓库必须逐个声明，不支持通配符
Composer 不扫描目录、不识别 * 或 **，"url": "../packages/*" 这种写法完全无效，会被直接跳过。每个本地包都得单独写一条 repositories 记录。
- 正确写法示例：
"repositories": [<br> {"type":"path","url":"../my-utils"},<br> {"type":"path","url":"../api-client"},<br> {"type":"path","url":"../../shared-components"}<br>] - 所有路径下的
composer.json必须各自有合法name，且不能重复；若两个包都叫acme/core，只有第一个生效 - 路径含空格或中文时，某些 PHP 版本会静默失败，建议避免
- 执行
composer update acme/utils不会自动git pull，本地 Git 状态需手动同步
路径、name、版本约束这三者对齐是硬性前提，缺一不可。最容易被忽略的是：repositories 写错位置、url 指向了 composer.json 文件而非目录、以及误以为 composer install 能触发 symlink 更新。
