Composer repositories配置受类型、顺序、包名匹配和稳定性约束共同影响，漏写type或顺序错误会导致静默忽略；vcs适用于Git等版本库，package用于静态定义单个包，composer指向第三方仓库服务。
Composer 的 repositories 配置不是“加一个源就能用”的简单开关，它受类型、顺序、包名匹配和稳定性约束共同影响；直接写错类型或放错位置，composer install 会静默忽略你的仓库，连报错都不会有。
repositories 必须显式声明 type，常见错误是漏写或写错
Composer 不接受无 type 的仓库定义。最常踩的坑是把私有 Git 仓库当成 vcs 类型却误写成 package 或直接省略——后者会导致整个仓库被跳过。
-
vcs：用于 Git/SVN/Hg 等版本控制系统，Composer 会自动探测分支和 tag，适用于开发中频繁更新的私有包 -
package：用于静态定义单个包（含完整name、version、dist或source），适合托管在对象存储或无法运行 Composer 服务的环境 -
composer：指向另一个支持packages.json的 Composer 仓库服务（如 Satis、Private Packagist），必须可公开访问或配置认证
示例（正确）：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/myorg/my-package.git"
}
]
}
包名冲突时，repositories 顺序决定优先级
Composer 按 repositories 数组从上到下的顺序扫描匹配包。如果你在 packagist.org 之前加了一个私有 vcs 仓库，且该仓库里有同名包（比如 monolog/monolog），Composer 就会拉取你仓库里的版本——哪怕它只是 fork 了旧版，这极易引发意外覆盖。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 想只覆盖特定包？用
package类型 + 精确name+version，避免全局污染 - 想优先用私有源但 fallback 到 Packagist？把私有源放前面，再加一条
{"type": "composer", "url": "https://packagist.org"}（注意：Composer 2.2+ 默认已内置，通常无需手动添加） - 调试是否命中？执行
composer show -a vendor/package，看输出中的source地址
private vcs 仓库需要认证，但凭据不能硬编码在 composer.json 中
Git over HTTPS 私有仓库若需 token 或账号密码，绝不能写在 composer.json 的 url 字段里（例如 https://token:x-oauth-basic@gitlab.example.com/...），既不安全，又容易被提交到代码库。
- 推荐方式：用
git config配置凭证助手（git config --global credential.helper store），或使用 SSH URL（git@gitlab.example.com:myorg/my-package.git）并确保部署机有对应 SSH key - CI 场景？在构建前注入
COMPOSER_AUTH环境变量，格式为 JSON：{"http-basic":{"gitlab.example.com":{"username":"ci-bot","password":"xxx"}} - 注意：SSH 方式下
type仍为vcs，Composer 会自动识别协议
require 中的版本约束必须与仓库实际提供的版本兼容
即使仓库配置正确，composer require vendor/package:dev-main 也可能失败——因为 vcs 类型仓库默认只暴露带 valid tag 的版本（如 v1.0.0），dev-main 这类开发分支名需明确启用 "minimum-stability": "dev" 且 "prefer-stable": false，否则会被过滤掉。
- 快速验证：运行
composer show vendor/package -a，检查列出的版本是否包含你要的分支或 tag - 若只提供 dev 分支，建议在仓库的
composer.json中设置"minimum-stability": "dev"，并在主项目中用"dev-main as 1.0.x-dev"这类 alias 显式映射 - GitLab/GitHub 的 protected branch 可能导致 Composer 拉不到分支信息，确认仓库设置允许 API 读取 refs
真正麻烦的从来不是加一行 repositories，而是当它没生效时，你得判断是网络、认证、类型、顺序、版本约束，还是 Packagist 缓存搞的鬼——建议每次改完先跑 composer clear-cache 再试。
