composer多仓库配置核心是repositories数组顺序即优先级、type严格匹配源类型、必须显式禁用packagist.org（"packagist.org": false），否则默认兜底导致私有包被覆盖或静默失败。
Composer 本身不支持 Monorepo，所谓“多仓库依赖管理”其实是用 path 类型仓库在根项目中手动伪造多个本地包源——配错任意一环，composer install 就会静默 fallback 到 Packagist，你改的代码根本不会加载。
为什么必须把 repositories 写在根 composer.json 里？
Composer 只扫描当前工作目录（即项目根）下的 composer.json 中的 repositories 字段，子包自己的 composer.json 里哪怕写满一百个 repositories，也完全被忽略。常见错误是把 {"type":"path","url":"packages/my-sdk"} 放进 packages/my-sdk/composer.json，结果 composer require myorg/my-sdk 依然去 Packagist 找包。
必须确保：
-
url是相对于根composer.json的精确路径，不能以./开头，也不能用绝对路径（协作必崩） - 若子包在
services/core/v2，就得单独加一条{"type":"path","url":"services/core/v2"}；"packages/*"不会自动递归匹配多级目录 - 修改
repositories后，必须运行composer clear-cache，否则可能读旧缓存导致路径失效
require 中的包名和版本为什么必须严丝合缝？
包名大小写、连字符、斜杠方向全部敏感："acme/utils" ≠ "Acme/Utils" ≠ "acmeutils"。写错一个字符，Composer 就放弃本地路径，转头去 Packagist 加载同名远程包——不报错，但你调试的永远是旧代码。
版本约束必须用本地标识：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 写
"acme/utils": "^1.0"：Composer 会跳过本地目录，去找 Packagist 上已发布的 1.x 版本 - 正确写法只有
"*@dev"、"@dev"或"dev-main"，表示“无条件取本地最新”，不走远程匹配逻辑 - 子包
composer.json中的version字段可省略；真正起作用的是name和路径一致性
符号链接（symlink）为什么不是默认行为？
预期中 vendor/acme/utils 应该是指向 packages/utils 的软链，这样改子包代码主项目立刻可见。但实际看到的是完整复制？说明 symlink 没建成功，Composer 已退化为 copy 模式。
原因包括：
- 未在
repositories条目中显式启用："options": {"symlink": true} - Windows 用户终端未以管理员身份运行，或未开启「开发者模式」（否则
mklink被禁用） - Linux/macOS 文件系统挂载了
noexec或nosymfollow - 软链建好后，若仍不生效，最稳妥方式是删掉
vendor/acme/utils目录再跑一次composer install
子包之间互相依赖时最容易漏掉什么？
比如 user-service require data-validator，而 data-validator 又 require core-utils。这种链式依赖下，所有被依赖方都必须出现在根 repositories 中，否则 Composer 解析依赖树时会卡住，静默 fallback 到远程。
还要注意 autoload 冲突：
- 每个子包的
autoload必须严格限定自身命名空间前缀，例如"MyOrg\Validator\": "src/"，绝不能写成"MyOrg\": "src/" - 根项目无需定义
autoload，它只作为协调者；所有类加载应由各子包自己声明并被 Composer 合并处理 -
autoload-dev默认不生效，哪怕子包自己写得再全也没用，需手动合并到根或通过其他机制注入
最隐蔽的坑不是配置写错，而是改完后没清缓存、没删 vendor 子目录、没确认 symlink 是否真生效——这些步骤缺一不可，否则你永远在调试一个“看起来对、其实没加载”的假环境。
