Composer安装指南：国内镜像加速实操-composer-PHP中文网

直接结论：不配国内镜像，90% 的 composer install 会卡在 “loading composer repositories” 或 “downloading” 阶段，不是你网络差，是 packagist.org 在国内根本连不上；必须严格满足 repo.packagist 键名、composer type 值、url 以 https:// 开头且末尾带斜杠三条件，并执行 composer clear-cache 和验证输出 json 才生效。

composer安装指南：国内镜像加速实操

直接结论：不配国内镜像，90% 的 composer install 会卡在 “Loading composer repositories” 或 “Downloading” 阶段，不是你网络差，是 packagist.org 在国内根本连不上。

为什么 `composer config -g repo.packagist` 总是没生效

这条命令静默失败的概率极高，它不报错、不提示，但实际回退到官方源——你根本不知道自己还在直连海外。核心就三个硬性条件，漏一个就废：

repo.packagist 是固定键名，写成 repos.packagist（多 s）、packagist.org 或 Repo.Packagist（大小写混用）全无效
composer 是 type 字段的**必须值**，不能省略，也不能当注释写在后面
URL 必须以 https:// 开头，且末尾带斜杠，比如 https://mirrors.aliyun.com/composer/ ✅，https://mirrors.aliyun.com/composer ❌（少斜杠会导致请求路径拼成 /composerpackages.json 直接 404）

验证是否成功？只看这一行输出：
composer config -g repo.packagist
正确结果要么是完整 JSON：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，要么是纯 URL 字符串（新版 Composer 行为）。返回空、null、报 Key not found 或仍是 https://packagist.org，说明配置根本没写进去。

项目级配置比全局更可靠，尤其在 CI 和宝塔环境

全局配置只对当前用户生效，而宝塔「一键部署」、GitHub Actions、Docker 构建默认用的是 www 或 runner 用户，根本读不到你本地 root 或个人用户的 ~/.composer/config.json。

进项目根目录（有 composer.json 的地方），执行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/
（注意：去掉 -g）

如果原 composer.json 里是 "repositories": {}（空对象），命令会自动 merge 进去
如果是 "repositories": []（空数组），命令会报错；此时需先手动改成对象结构再运行
已有私有仓库？别手写 JSON —— 手动编辑极易引号不全、逗号遗漏、方括号错位，用命令追加最安全
改完务必删掉 vendor/ 和 composer.lock，再跑 composer install，否则旧 lock 文件里的哈希可能和镜像元数据不匹配

`--repository-url` 临时换源，排查问题第一选择

不想改任何配置，又想确认某个镜像是否真有效？或者 CI 脚本里要隔离环境？用 --repository-url 参数，优先级最高，只影响当次命令：

Composer

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

下载

composer create-project laravel/laravel myapp --repository-url=https://mirrors.tuna.tsinghua.edu.cn/composer/
composer update -vvv --repository-url=https://mirrors.cloud.tencent.com/composer/

加 -vvv 很关键：它会打印出实际发起的 HTTPS 请求 URL，一眼就能看出走的是哪个域名。这是判断“为什么还是慢”的唯一可靠依据——不是猜，是看日志。