解析Composer国内镜像的底层加速逻辑-composer-PHP中文网

composer加速需分两层：元数据走镜像（如阿里云），zip包仍直连github；换镜像后必须删除vendor和composer.lock并重装，才能更新lock中dist.url字段，否则下载仍卡在codeload.github.com。

解析composer国内镜像的底层加速逻辑

Composer下载分两层：元数据和zip包走不同路径

Composer 的加速不是“换一个源就全快了”，它实际分两个独立环节：packagist.org 提供的元数据（包名、版本、依赖关系）和 GitHub 提供的实际 zip 包。国内镜像（如阿里云、腾讯云）只代理前者，不托管后者——也就是说，composer install 时，元数据从镜像站拉，但 zip 文件仍默认从 https://codeload.github.com/ 下载。

这就是为什么配了镜像还卡在 Downloading https://codeload.github.com/... 的根本原因：镜像没接管 zip 下载路径，而 GitHub 在国内直连极不稳定。

元数据请求走 https://mirrors.aliyun.com/composer/packages.json 等接口，响应快、可 CDN 加速
zip 包请求走 https://codeload.github.com/{user}/{repo}/legacy.zip/{ref}，受 DNS、TLS、GFW 影响大
镜像站不提供 zip 托管服务（成本高、合规风险大），所以没有“一键全链路加速”这回事

composer.lock 里的 dist.url 决定 zip 实际下载地址

真正控制 zip 下载地址的是 composer.lock 文件中每个包的 dist.url 字段。这个字段在首次 composer install 时由 Composer 根据当前元数据源生成，并固化进 lock 文件——**换镜像后，旧 lock 文件里的 dist.url 仍是原始 GitHub 地址，不会自动更新**。

现象：执行 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 后，composer install 依然慢；-vvv 日志里仍出现 Downloading https://codeload.github.com/。

Composer

Composer 是 PHP 生态常用依赖管理工具，用于安装框架、组件和项目依赖。

下载

必须删掉 vendor/ 和 composer.lock，再跑 composer install，才能让新镜像生成新的 dist.url
--repository-url 参数只影响元数据拉取，对已存在的 composer.lock 完全无效
如果项目用了私有仓库或 Satis 源，dist.url 可能指向内网地址，此时换镜像反而会破坏构建

repo.packagist 配置写错一个字符就静默失效

Composer 对 repo.packagist 配置极其敏感：键名、type 值、URL 格式三者缺一不可，且任何错误都不报错，只默默 fallback 到官方源。这是最常被忽略的底层逻辑——你以为配好了，其实什么都没变。

验证方式只有且仅有一条：composer config -g repo.packagist 输出必须是完整 JSON 或纯 URL 字符串。空、null、Key not found 或仍显示 https://packagist.org，说明配置根本没写进去。

键名必须是 repo.packagist（不能是 repos.packagist、packagist、Repo.Packagist）
命令中必须显式写出 composer 作为 type 值：composer config -g repo.packagist composer https://...
URL 必须以 https:// 开头，且末尾带 /：https://mirrors.aliyun.com/composer/ ✅，少斜杠会拼出 /composerpackages.json 导致 404
全局配置只对当前用户生效，宝塔、CI、Docker 中运行用户 ≠ 配置用户，需切到对应用户下重配

项目级配置比全局更可控，但要注意 repositories 覆盖行为

在 composer.json 里写 "repositories": [{"type": "composer", "url": "..."}] 是优先级最高的方式，但它不是“追加”，而是**全量替换**整个 repositories 数组。如果你已有私有 Git 源或本地 path 仓库，用 composer config repo.packagist ...（不加 -g）会清空它们。

正确做法是手动编辑 composer.json，在 repositories 数组开头或结尾插入一条 packagist 镜像记录，保留原有条目。否则那些私有包将直接不可见。

已有 "repositories": []（空数组）？先改成 "repositories": {}（空对象），再运行命令，Composer 会自动转为标准数组并追加
已有 "repositories": [{...}]？别用命令覆盖，手动加一行更安全
CI 环境推荐用 composer install --repository-url=https://...，避免配置污染和用户权限问题

实际生效的关键不在“配了多少”，而在 composer.lock 是否重建、dist.url 是否刷新、repo.packagist 是否精准写入——这三个点任意一个断开，镜像就只是个摆设。