composer repositories 是 composer.json 中用于扩展包搜索范围的配置项，不是替代 require 或自动拉取代码的机制；需按顺序配置多个仓库，私有仓库置前、公共镜像置后，packagist.org 禁用项必须单独成数组元素且建议放最后。
composer repositories 是什么，不是什么
repositories 是 composer.json 里的一个配置项，用来告诉 Composer：「除了 packagist.org，我还从这些地方找包」。它不替代 require，也不自动拉取代码——只是扩展了包的搜索范围。很多人误以为配了就能直接 composer require vendor/name，结果报 Could not find package，其实是没搞清：包必须在你配的某个仓库里真实存在，且 name 和 version 能被解析到。
怎么写多个仓库，顺序很重要
多个仓库用数组写，顺序决定优先级：Composer 会从上到下依次查找，找到第一个匹配的就停。所以私有包仓库要放前面，公共镜像（比如阿里云镜像）放后面兜底。
常见错误是把 packagist.org 的禁用和自定义仓库混在一起写错位置：
{
"repositories": [
{
"type": "vcs",
"url": "https://git.example.com/my-private-package"
},
{
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
},
{
"packagist.org": false
}
]
}
上面这段会报错，因为 {"packagist.org": false} 不是合法仓库对象。正确写法是单独一项：{"packagist.org": false} 必须是数组中的一项，且建议放在最后（否则它会提前截断查找）：
- 每个仓库对象必须有
type字段，常见值：vcs、composer、package -
{"packagist.org": false}是特殊语法，不是仓库，不能带其他字段 - 所有
composer类型仓库的url必须以/结尾（如https://repo.example.com/），否则composer install可能静默失败
vcs 仓库为什么经常拉不到 dev-main
用 type: "vcs" 指向 Git 仓库时，Composer 默认只识别带稳定版本号的 tag（如 v1.0.0），不会自动把 main 或 develop 分支当 dev-main 处理——除非你在 require 里明确写死分支名。
常见现象：composer require myorg/mylib:dev-main 报 Could not find package，但 git clone 能通。
- 确认 Git 仓库根目录有
composer.json，且name字段和require里写的完全一致（包括大小写） - 分支名必须加
dev-前缀才能被识别，main→dev-main，next→dev-next - 如果要用
dev-main，确保该分支的composer.json中version字段要么不存在，要么设为"dev"；设成"1.0.0"反而会被忽略 - VCS 仓库不支持按路径过滤，整个仓库的所有分支/Tag 都会被索引，可能拖慢
update
私有 Composer 仓库（type: composer）的最小可用配置
如果你搭了 Satis 或 Private Packagist 这类服务，type: "composer" 是最常用方式。但它不像 VCS 那样“即插即用”，依赖服务端生成的 packages.json。
最容易被忽略的是：服务端返回的元数据必须包含完整包信息，且路径可公开访问。本地测试时，常因 Nginx 未配 try_files 或缺少 index.php fallback 导致 404。
-
url必须指向含packages.json的目录，例如https://packages.myorg.com/，而不是https://packages.myorg.com/packages.json - 服务端响应头需包含
Content-Type: application/json，否则 Composer 解析失败，报错类似file could not be downloaded: failed to open stream - 如果服务启用了 Basic Auth，必须在
url里写成https://user:pass@packages.myorg.com/，Composer 不会弹认证框 - 运行
composer clear-cache后再update，否则旧缓存可能掩盖配置生效问题
多仓库场景下，最麻烦的永远不是怎么写，而是哪个仓库悄悄覆盖了你的预期版本——尤其当两个仓库都提供同名包时，靠位置顺序和稳定性标记（stable vs dev）来博弈，得盯紧 composer show -a vendor/name 的输出。
