Composer 的 repositories 配置直接影响包发现与安装行为，错误配置会导致找不到包、降级失败或静默使用错误源；其类型（packagist/composer/vcs/package）和顺序决定元数据获取逻辑，且自定义源需严格遵循协议与路径规范。
Composer 的 repositories 配置不是“加个源就能用”的简单开关，它直接影响包发现、版本解析和安装行为——错误配置会导致 composer install 找不到包、降级失败、甚至静默使用错误源。
repositories 是什么，以及它为什么不能乱写
repositories 是 Composer 在执行 composer install 或 composer require 时查询包元数据（composer.json）的源头列表。默认只有 Packagist.org，添加自定义源后，Composer 会按顺序遍历所有仓库，直到找到匹配的包名和版本约束。
- 顺序很重要：靠前的仓库优先匹配，即使后面有更合适的版本也不会回退
- 类型决定行为：
packagist、composer、vcs、package四种类型解析逻辑完全不同 - 不校验可用性：配置了但服务不可达，只会报错
Could not fetch packages...，不会自动跳过
最常用的 type: "composer" 自定义源怎么配才生效
这是私有 Packagist 兼容源（如 Satis、Private Packagist、JFrog Artifactory）的标准接入方式。关键不是 URL，而是该地址必须能返回符合 Composer API 协议的 packages.json 索引文件。
{
"repositories": [
{
"type": "composer",
"url": "https://my-private-repo.example.com"
}
]
}
- URL 必须以
/结尾，否则 Composer 会拼出错误路径（如请求https://x.y.z/packages.json而非https://x.y.z//packages.json） - 该地址需支持 HTTPS 且证书有效；HTTP 仅在
config.allow-plugins.composer/installers显式允许时才可能工作（不推荐） - 如果源启用了认证，必须提前运行
composer config http-basic.my-private-repo.example.com username token - 不建议在项目级
composer.json中硬编码凭证，应通过全局auth.json管理
type: "vcs" 用于 Git 仓库时的典型陷阱
当你要直接从 GitHub/GitLab/自建 Git 服务器安装某个尚未发布到 Packagist 的分支或提交，vcs 类型最常用，但极易因路径或分支名不一致导致安装失败。
- 仓库 URL 必须是可克隆地址（
git@或https://），且 Composer 能访问（如 SSH key 已配置、HTTPS 无需交互登录） - 包名（
name字段）必须与composer.json中声明的完全一致；Composer 不会根据 URL 推断包名 - 若目标分支没有
composer.json，或其version字段为dev-xxx，则只能用dev-xxx作为版本约束（如"monolog/monolog": "dev-main"） - 不支持通配符或模糊匹配：写
"dev-*"不会自动选最新分支，只会报错Could not find package...
require 里的包名冲突和 packagist.org 的隐式禁用
一旦你在 repositories 中声明了任何非-packagist 类型源（比如 type: "composer" 或 type: "vcs"），Composer 默认会**关闭对 packagist.org 的自动查询**——除非你显式加上官方源：
{
"repositories": [
{
"type": "composer",
"url": "https://my-private-repo.example.com"
},
{
"type": "packagist",
"url": "https://packagist.org"
}
]
}
- 漏掉这个
packagist条目，所有未在私有源中注册的包（比如symfony/console）都会安装失败 - 如果你只想让部分包走私有源，其余走官方源，必须确保私有源只包含这些包的元数据，且顺序放在
packagist之前 -
packagist.org的 URL 可以省略，写成{"type": "packagist"}即可，但显式写出更清晰
真正难的不是写配置，而是理解每个字段如何参与 Composer 的包解析流水线——尤其是 type 和 url 如何共同决定元数据获取路径，以及 repositories 列表顺序如何覆盖默认行为。一个没注意的斜杠、一次漏掉的 packagist 声明，就足以让 CI 流水线卡住半小时。
