因为 composer 2.5+ 仅认 repo.packagist 这一固定键名，repositories.packagist 等错误写法会被静默忽略，且必须显式指定 type: "composer" 和带末尾斜杠的 url 才生效。
为什么直接配 repositories.packagist 不管用？
因为这个配置只接管整个 Packagist.org 的元数据查询，不区分 vendor 或组织。哪怕你把阿里云镜像写进 composer.json，monolog/monolog 和 topthink/framework 都会走同一个源——它没法按前缀分流。
Composer 本身没有 vendor-specific-mirror 这种机制，所谓“对特定组织用专属镜像”，本质是绕过自动解析，手动声明包。
怎么用 type: package 绑定组织级镜像？
核心是：把目标组织下所有你想加速的包，逐个或批量声明为 type: "package"，并显式指定 dist.url 指向该组织对应的镜像 ZIP 地址。
常见错误现象：
- 改了
repositories但composer install还是从 packagist.org 下载 ZIP -
composer update -vvv日志里看到的仍是@#@#@#@#@#@#@#@#@#@0...而非镜像域名
实操要点：
- 必须在项目根目录
composer.json的repositories数组里添加条目，不是在依赖包自己的composer.json里 - 每个包必须写死
version和dist.url，不能留"dev-main"这类动态版本（否则 Composer 无法匹配） - 镜像 ZIP 地址格式要和原包一致，比如腾讯云对
topthink/thinkv8.0.0 的地址通常是：@#@#@#@#@#@#@#@#@#@1 - 如果一个组织有多个包，得每个都单独列，不能用通配符
示例（强制 topthink/* 全走腾讯云）：
{
"repositories": [
{
"type": "package",
"package": {
"name": "topthink/think",
"version": "8.0.0",
"dist": {
"url": "https://mirrors.cloud.tencent.com/composer/p2/topthink/think/8.0.0.0-zip-abc123.zip",
"type": "zip"
}
}
},
{
"type": "package",
"package": {
"name": "topthink/framework",
"version": "6.2.0",
"dist": {
"url": "https://mirrors.cloud.tencent.com/composer/p2/topthink/framework/6.2.0.0-zip-def456.zip",
"type": "zip"
}
}
}
]
}
如何避免 composer.lock 锁死旧源？composer.lock 文件里硬编码了每个包的 dist.url 和 source.url。哪怕你改完 composer.json 并加了 type: package，只要 lock 文件没更新，composer install 就仍按旧地址拉包。
必须做两件事：
- 删除
composer.lock（或至少删掉里面对应包的dist字段） - 运行
composer update topthink/think topthink/framework --no-cache，而不是install
如果项目已上线，不能随便删 lock 文件，那就得用 composer update --with-dependencies 精准刷新依赖链，再确认 -vvv 日志中下载 URL 已切换。
为什么不能靠 --repository-url 临时切换？composer require topthink/think --repository-url https://mirrors.cloud.tencent.com/composer/ 看似能临时指定源，但它只影响元数据获取阶段（即查有哪些版本），不改变包最终的 dist.url。如果该镜像没重写 ZIP 地址，Composer 仍会从原始 GitHub 或 GitLab 地址下载。
真正生效的只有两种路径：
- 全局或项目级
repo.packagist配置（适用于全部包） -
type: package手动声明（适用于特定包，且必须控制dist.url）
后者才是唯一能确保“特定组织 → 专属镜像”的方式，但代价是维护成本高、版本需同步及时。
实际落地时最容易被忽略的点：镜像站是否真的提供了该组织包的 ZIP 缓存。有些镜像只同步元数据，不缓存 dist 文件；此时即使你写了正确的 dist.url，也会返回 404。验证方式只有 curl -I 直接测那个 URL。
