composer卡在loading或downloading阶段必须严格换国内镜像：配置键名、type值、https末尾斜杠、-g参数缺一不可；已有lock文件需composer update --lock重写dist.url；ci/docker等环境应改用项目级配置并提交composer.json。
composer 卡在 Loading composer repositories 或 Downloading 阶段，基本就是没走国内镜像——换源不是“试试看”，而是必须严格配对命令、清缓存、验证实际请求地址。
composer config -g repo.packagist 命令为什么总不生效
这不是镜像本身问题，是配置根本没写进去，Composer 2.2+ 会静默 fallback 回packagist.org，且不报错。
- repo.packagist 键名不能写成 repos.packagist（多一个 s）、packagist（少 repo. 前缀）或 repositories.packagist（层级错）
- 中间的 composer 是 type 值，不是可选参数，漏掉就失效
- URL 必须是 HTTPS + 末尾带斜杠：https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9 ✅，https://mirrors.aliyun.com/composer ❌（少斜杠导致拼出 /composerpackages.json 返回 404）
- 必须加 -g，否则只改当前项目 composer.json，换目录就失效
验证是否成功：运行 composer config -g repo.packagist，输出必须是完整 JSON，形如 {"type": "composer", "url": "@#@#@#@#@#@#@#@#@#@0"}。空、null、字符串 URL 或报错，都说明没写进 ~/.composer/config.json。
换了镜像还是卡在 downloading xxx.tar.gz
镜像只加速元数据（packages.json）和 dist 包下载，但 composer.lock 里存的是原始 dist.url，Composer 会先尝试这个地址，失败后才 fallback——而 fallback 不保证成功，尤其对 hyperf/*、workerman/* 这类体积大的包。
- 已有 composer.lock 的项目，必须执行 composer update --lock 强制重写所有 dist.url 字段为镜像路径
- 新项目用 composer create-project 时，直接加 --repository=https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9 更可靠
- 验证是否真走镜像：打开 composer.lock，找任意一个包的 dist.url，应为类似 https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9dists/... 的路径
全局配置在 CI/宝塔/Docker 里为啥不起作用
-g 写的是当前用户（比如你本地 root 或 admin）的 ~/.composer/config.json，但 CI 流水线、宝塔后台、Docker 容器常以 www、runner 或其他受限用户身份运行，压根读不到你的配置。
- 推荐改用项目级配置：composer config repo.packagist composer https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9（去掉 -g），它会自动往 composer.json 的 repositories 字段里安全追加，不覆盖已有私有源
- 如果 composer.json 原本是 "repositories": {}，命令会转成标准数组并插入；如果是 "repositories": []，则向末尾 push 新项
- 提交 composer.json 到 Git，CI 和协作者拉取即生效，无需额外环境配置
镜像选哪个？阿里云、清华、华为云差异在哪
三者都可用，但同步节奏和网络表现不同： - 阿里云镜像：同步延迟通常 5–10 分钟，CDN 覆盖广，适合大多数场景 - 清华源（https://mirrors.tuna.tsinghua.edu.cn/composer/）：IPv6 支持更稳，部分地区直连更快
- 华为云（https://mirrors.huaweicloud.com/repository/php/）：偶尔延迟半小时以上，新包发布后建议等一等再试
- 别用已停服的旧地址：https://packagist.phpcomposer.com（返回 404）、https://packagist.laravel-china.org（2025 年底下线）
换源之后第一次 composer install 可能稍慢（重建缓存），但后续所有操作都会明显提速。真正容易被忽略的是：镜像只代理 packagist.org 官方仓库，私有包、GitHub 直链包、VCS 类型依赖仍需单独配置，不能指望一个镜像解决全部下载问题。
