Composer不支持自动切换备用仓库，每次仅使用一个repo.packagist.org配置，后设值覆盖前值；所谓“备用”必须依赖外部脚本、环境变量或alias手动实现。

Composer 不支持“自动切换备用仓库”——它每次只用一个 repo.packagist.org 配置，后设值直接覆盖前值；所谓“备用”，必须靠外部控制流实现。

---

composer config -g repo.packagist.org 只能设一个地址

• 这个命令改的是全局配置项 repo.packagist.org，底层对应 Packagist 官方源的镜像地址
• 写两遍 composer config -g repo.packagist.org <a href="https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9">https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9</a>，第二条会彻底覆盖第一条
• 不存在“主+备”字段，也不存在 fallback、mirror 或 priority 这类配置键

常见错误现象：

• 在 composer.json 的 repositories 里重复写两个 packagist.org 条目 → Composer 报错或静默忽略后一个
• 以为加了多个 type: composer 源就能自动 fallback → 实际只按顺序匹配，不重试

实操建议：

• 用 shell alias 快速切换（推荐）：

  alias composer-aliyun='composer config -g repo.packagist.org https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9'
  alias composer-tencent='composer config -g repo.packagist.org https://mirrors.cloud.tencent.com/composer/'

• 切换后执行 composer config -g repo.packagist.org 确认当前生效地址
• 切勿在项目级 composer.json 里硬编码 repo.packagist.org ——它只接受全局配置

---

用 COMPOSER<em>REPO</em>[NAME]_URL 环境变量临时启用备用源

• 这是唯一真正支持“运行时动态多源”的机制，且不修改任何配置文件
• 命名规则严格：COMPOSER_REPO_MY_PRIVATE_REPO_URL=<a href="https://www.php.cn/link/bd60b7054e3090a6a7b3fc94f4d9d17f">https://www.php.cn/link/bd60b7054e3090a6a7b3fc94f4d9d17f</a>
• MY_PRIVATE_REPO 是你自定义的仓库别名，不能含点、斜杠等特殊字符
• 同时可配 COMPOSER_DISABLE_PACKAGIST=1 关闭默认源，避免冲突

使用场景：

Academic Composer Upload

辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

下载

• CI/CD 流水线中根据环境变量拉不同私有源
• 本地调试时快速切到测试镜像，不污染全局配置
• 多团队共用同一份 composer.json，但各自用不同私仓

注意点：

• 环境变量只在当前命令生命周期有效，需 export 后再跑 composer install
• 不会写入 composer.lock，所以 lock 文件里不会记录该源地址
• 若同时存在 repositories 数组和同名环境变量仓库，环境变量优先级更高

---

repositories 数组里放多个源 ≠ 备用，而是「优先级队列」

• repositories 是数组，Composer 从上到下逐个查包，命中即停
• 想让私有源优先于 packagist.org，必须：
  • 把私有源放在 repositories 数组最前面
  • 显式加 {"packagist.org": false} 条目禁用默认源（不能只删掉它）
• 错误写法示例：

  "repositories": [
    {"type": "composer", "url": "https://www.php.cn/link/bd60b7054e3090a6a7b3fc94f4d9d17f"},
    {"packagist.org": false}
  ]

  → 这样 packagist.org 条目在后面，无效；正确位置应在**第一个**

容易踩的坑：

• 以为写了两个 type: composer 源就能自动 fallback → 实际是“谁在前面谁生效”，后面的根本不查
• 忘记删 composer.lock 或没加 --lock 参数 → composer install 仍按旧 lock 文件拉包，新源不生效
• 私有源返回 404 或空 packages.json → Composer 不报错，只安静跳过，最终报 Could not find package

---

真正需要“备用”逻辑的地方，得自己写 wrapper 脚本捕获 composer install 的退出码，失败后自动换源重试。这不是 Composer 内置能力，而是运维侧补足。多数情况下，用环境变量或 alias 切换，比搞自动 fallback 更可控、更易 debug。