如何详细操作在Composer中添加多个仓库（repositories）？

本文共计1138个文字，预计阅读时间需要5分钟。

Composer 添加多个 repositories 并不是简单地在 `composer.json` 中堆砌 URL。正确做法是在 `composer.json` 中指定 URL，并注意它们的顺序——错误的顺序、类型混淆或遗漏禁用默认源都可能导致无法生效。即便如此，默认情况下仍会从 packagist.org 静默下载，除非基本安装失败。

repositories 数组必须是索引数组，且顺序 = 优先级

Composer 按 repositories 数组从上到下的顺序查找包，找到第一个匹配的就停，**不会 fallback 到后面仓库**。这不是容错机制，是硬性短路逻辑。

• 私有仓库想覆盖同名公开包（比如 monolog/monolog），必须放在数组最前面
• 写成对象（如 "my-repo": { "type": "composer", ... }）会导致只生效最后一个——必须用方括号 []，每个元素是独立的 {"type": "...", "url": "..."}
• CI 构建失败常见原因是本地全局 ~/.composer/config.json 里也配了 repositories，但项目级配置优先级更高；建议统一在项目 composer.json 中声明，避免环境不一致

type 必须显式指定，vcs 和 composer 行为完全不同

vcs 类型只服务于你 require 中明确写的那个包名，且仅当该 Git 仓库根目录存在 composer.json 才能被识别；composer 类型则是完整索引服务，支持搜索、版本发现和依赖解析。

• vcs：适合单个私有库快速接入，URL 可以是 git@gitlab.example.com:org/pkg.git 或 https://token:x-oauth-basic@gitlab.example.com/org/pkg.git，但凭据绝不能硬编码进 composer.json
• composer：适合团队级私有 Packagist（如 Satis、Private Packagist），URL 必须可访问 packages.json，且需额外配置 auth.json 认证
• 混用 vcs 和 composer 在同一数组中没问题，但别指望 vcs 仓库里的包能被 composer search 扫到——它不参与全局索引

packagist.org 不是默认“保底”，必须显式声明或显式禁用

一旦你写了 repositories 数组，Composer 就会**完全忽略隐式 packagist.org**。如果你只加了私有源却没再把官方源加回来，连 monolog/monolog 这类基础包都装不了。

• 想保留官方源：在数组末尾加上 {"type": "composer", "url": "https://packagist.org"}
• 想彻底禁用官方源（防污染）：在 composer.json 根级加 "packagist.org": false，注意这不是 repositories 的子项
• 错误写法："repositories": [{...}, {"type": "composer", "url": "https://packagist.org"}] + 漏掉 "packagist.org": false → 私有包可能被跳过，因为 packagist.org 虽然在最后，但它的索引更全，反而抢答成功

auth.json 是唯一合法认证方式，且位置必须正确

私有 vcs 或 composer 仓库需要认证时，auth.json 不能缺，也不能放错地方——否则 composer update 会卡在 401，连错误提示都可能被日志级别掩盖。

• 推荐路径：项目根目录下放 auth.json（和 composer.json 同级），内容如 {"http-basic": {"my-private-repo.example.com": {"username": "user", "password": "token"}}}
• 全局路径也可用：~/.composer/auth.json 或 $COMPOSER_HOME/auth.json，但 CI 场景建议用 COMPOSER_AUTH 环境变量注入 JSON 字符串
• Git SSH 方式下，auth.json 不需要配，但得确保部署机已加载对应 SSH key（ssh-add -l 可验证）
• 改完 auth.json 后，composer update --dry-run 可提前验证是否能连通

最容易被忽略的是 lock 文件缓存行为：composer install 完全不读 repositories 配置，它只按 composer.lock 里记录的 source 安装；换源后必须跑 composer update --lock 或删 lock 重来，否则永远拉不到新地址的包。