Composer多仓库需显式声明packagist.org，按顺序优先匹配且不回退；vcs仓库不参与全局搜索，仅限明确require的同名包；私有仓库须配置auth.json认证并确保元数据实时更新。
Composer 支持同时配置多个 repositories，但必须注意：**只有第一个匹配的包会被安装，后续仓库不会回退查找**。也就是说，它不是“fallback 机制”，而是“优先级顺序匹配”。
如何正确声明多个 repositories（含 packagist.org）
默认情况下，Composer 会隐式启用官方源 packagist.org。一旦你手动定义了 repositories 数组，这个默认源就会被完全覆盖——除非你显式把它加回去。
常见错误是只写私有仓库，结果连 monolog/monolog 这类通用包都装不上。
- 必须把
packagist.org显式声明为 typecomposer的仓库，且url设为https://packagist.org - 私有仓库建议放在数组前面（如果希望优先命中），但要确认其
packages元数据已更新（如 Satis 或 Private Packagist） - 所有仓库的
type必须一致（composer、vcs、package等不能混用在同一逻辑用途中）
{
"repositories": [
{
"type": "composer",
"url": "https://my-private-repo.example.com"
},
{
"type": "composer",
"url": "https://packagist.org"
}
],
"require": {
"vendor/private-package": "^1.0",
"monolog/monolog": "^2.10"
}
}
使用 vcs 类型仓库时为什么总是 fallback 失败
vcs 类型仓库（如 Git）不提供完整包索引，Composer 只会在明确 require 了该仓库中某个 name 的包时，才临时去对应 Git 地址解析 composer.json。它**不会参与全局包搜索**，所以不能当作“备用源”来用。
典型现象：composer require vendor/missing-package 报错 Could not find package...，即使该包在某个 Git 仓库里存在。
- 仅当
name完全匹配composer.json中的name字段时，vcs 才生效 - 无法支持通配符或模糊匹配（比如
vendor/*） - 若多个 vcs 仓库包含同名包，以
repositories数组中靠前的为准，后一个完全被忽略
私有仓库 require 后仍报 401 或 403 怎么办
HTTP 状态码错误通常不是配置问题，而是认证未透传。Composer 不会自动携带系统凭据（如 ~/.netrc 或 git credential）到私有 Composer 仓库请求中。
- 确保私有仓库 URL 使用
https://协议，并已配置auth.json -
auth.json必须和composer.json在同一目录，或置于 COMPOSER_HOME 目录下（如~/.composer/auth.json） - 格式必须是双层结构：
{"http-basic": {"my-private-repo.example.com": {"username": "...", "password": "..."}}} - 密码建议使用 Personal Access Token（PAT），而非账户密码，尤其在 CI 环境中
{
"http-basic": {
"my-private-repo.example.com": {
"username": "token",
"password": "ghp_xxx..."
}
}
}
多仓库最易被忽略的是元数据时效性：私有 Composer 仓库（如 Satis）必须定期 build，否则新增的包版本根本不会出现在 packages.json 里，Composer 就算配置对了也查不到。
