Composer install卡顿90%因未正确配置国内镜像，必须执行composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，严格满足键名单数、type为composer、URL以HTTPS结尾斜杠三要素，否则静默失效。
国内 PHP 项目跑不起来，90% 是因为 composer install 卡在 Downloading 或直接超时——不是你网络差，是默认走海外 https://packagist.org，DNS 解析慢、TLS 握手失败、首字节延迟高，三重卡点叠加。配镜像不是“提速技巧”，而是能正常工作的前提。
确认当前是否真用了国内镜像
别信 composer diagnose 显示 “OK” 就以为源生效了——它只验语法和本地连通性，不查镜像元数据是否完整。真正有效的验证方式只有两个：
- 运行
composer config -g repo.packagist，输出必须是类似{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}的完整 JSON；空值、null、或仍显示https://packagist.org，说明没写进去 - 执行
composer install -vvv，日志里所有Downloading行的域名必须是镜像地址（如mirrors.aliyun.com），而不是api.github.com或packagist.org
常见误判点：composer config -g repos.packagist（多一个 s）会静默失败，不报错也不输出；composer config repo.packagist（漏掉 -g）只改当前项目，换目录就失效。
全局配置命令必须严格满足三要素
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 这条命令里，三个要素缺一不可：
立即学习“PHP免费学习笔记（深入）”；
- 键名必须是
repo.packagist（单数，不是repos） - 中间的
composer是协议类型，不能省略，否则 Composer 认为这是普通仓库，后续仍 fallback 到官方源 - URL 必须以
https://开头，且末尾带/；写成https://mirrors.aliyun.com/composer（少斜杠）会导致路径拼接出错，比如变成/p2//，直接 404
Windows 用户需以管理员身份运行命令行；macOS/Linux 下若提示权限拒绝，检查 ~/.composer/config.json 所在目录写入权限。配错后先用 composer config -g --unset repo.packagist 清掉再重试。
项目级配置会无声覆盖全局设置
哪怕你刚配好阿里云镜像，只要项目根目录的 composer.json 里有 repositories 字段，全局配置就完全失效——而且 Composer 不报任何警告。
典型问题场景：
-
"repositories": [{"type": "composer", "url": "https://packagist.org"}]：明摆着走官方源，但开发者以为“配了全局就万事大吉” -
"repositories": [{"type": "package", "url": "..."}]：混用了私有包定义，触发 Composer 按顺序尝试所有源，卡在某个失效源上超时 - 团队协作时误传带
repositories的composer.json，CI 构建失败第一件事就是 grep 这个字段
临时调试可用 composer update --repository-url=https://mirrors.tuna.tsinghua.edu.cn/composer/，它会绕过 composer.json 里的 repositories，只用你指定的源。
镜像选哪个？阿里云最稳，但得配合验证
截至 2026 年 7 月，实测稳定、支持 HTTPS 和 Composer 2.9.6 的主流镜像有四个：
-
https://mirrors.aliyun.com/composer/：华东/华北响应最快，Laravel 11 / PHP 8.4 新包基本当天入库，适合生产环境 -
https://mirrors.tuna.tsinghua.edu.cn/composer/：教育网和北方地区极快，但南方偶发 DNS 解析慢；对 PHP 8.4 函数签名兼容性验证更严 -
https://packagist.mirrors.sjtug.sjtu.edu.cn/：学术网络运维，稳定性优先，但需确认出口 IP 是否在教育网白名单内，否则返回 403 -
https://php.cnpkg.org：非官方但更新最勤，Laravel 11 和 monorepo 类包几乎当天入库，缺点是文档弱，出问题只能靠社区反馈
千万别碰已停用的 https://packagist.phpcomposer.com（2025 年底起频繁 502）和 https://packagist.laravel-china.org（已停止维护）。配完记得用 curl -I https://mirrors.aliyun.com/composer/packages.json 测试是否秒回 HTTP/2 200——镜像配置成功 ≠ 镜像服务可用。
最易被忽略的一点：镜像只加速 Packagist 上的 public 包；如果依赖里含 GitHub 直链、私有 Git 仓库或 ext- 扩展，镜像完全无效。此时 composer.lock 中记录的 dist.url 若仍是原始 GitHub 地址，就得删掉 composer.lock 和 vendor/ 后重装。
