必须切换国内镜像源才能解决 composer install 卡顿问题，推荐全局配置阿里云镜像（需 composer 2.1+），执行 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 并清缓存，再验证配置与网络请求是否生效。

PHP框架项目初始化时，composer install 卡在 loading package information 或 resolving dependencies，本质是 packagist.org 国内直连失败导致的元数据加载阻塞，必须切换国内镜像源才能继续——这不是可选项，而是执行 composer 命令前的强制前置动作。

全局启用阿里云镜像（推荐首选）

阿里云镜像同步最快、CDN节点覆盖全、HTTPS稳定，且对 Composer 2.1+ 版本兼容性最好，适合作为开发机默认源。

第一步：确认 Composer 版本不低于 2.1，运行 composer --version，若输出低于 Composer version 2.1.0，先执行 composer self-update 升级。

第二步：执行命令写入全局配置：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。

注意：漏掉 -g、键名错写成 repos.packagist、URL 尾部缺 / 或中间漏掉 composer 这个 type 值，任一出错都会静默回退官方源，且不报任何错误。

第三步：立即清空本地缓存，否则旧元数据仍会拉取失败：composer clear-cache。

验证镜像是否真实生效

不能只看安装速度变快，要查真实配置和网络行为。

运行 composer config -g repo.packagist，输出必须是完整 JSON 对象，例如：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。如果为空、null 或报 Key not found，说明配置未写入成功。

再运行 composer diagnose，观察 “Repo” 行显示的 URL 是否包含 mirrors.aliyun.com；若仍是 https://packagist.org，大概率被项目级 repositories 字段覆盖了。

最后，在项目根目录下执行 composer install -vvv，日志中首次请求的 packages.json 地址应为 https://mirrors.aliyun.com/composer/packages.json，而非 packagist.org 域名。

按需切换项目级镜像

当团队协作要求统一锁定源，或某项目依赖私有包、审计强制隔离时，应避免依赖开发者本地全局配置。

方法一：进入项目根目录后，去掉 -g 参数执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/。该命令会向当前项目的 composer.json 中写入 repositories 字段。

方法二：手动编辑 composer.json，在顶层添加如下字段（注意缩进与逗号）：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

"repositories": [{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}]。

注意：若项目已有 repositories 字段，直接追加数组项即可，不要覆盖原有内容；否则可能丢失私有仓库声明。

临时绕过镜像（调试专用）

某些刚发布的 beta 包在镜像中尚未同步，或你怀疑镜像本身异常，需要单次直连官方源验证。

在任意目录下运行：composer install --repository=https://packagist.org。

这个参数仅对本次命令生效，不会修改任何配置文件，退出终端即失效。

⚠️ 提示：--repository 后必须是完整 HTTPS URL，不能省略协议头，也不能用短域名如 packagist.org。

多镜像地址对照表（一键复制）

不同镜像稳定性与适用场景略有差异，以下为截至 2026 年 8 月仍在稳定服务的主流地址：

阿里云：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

腾讯云：composer config -g repo.packagist composer https://mirrors.cloud.tencent.com/composer/

华为云：composer config -g repo.packagist composer https://mirrors.huaweicloud.com/repository/php/composer/

中科大：composer config -g repo.packagist composer https://packagist.mirrors.ustc.edu.cn/

清华源（同步及时，IPv6 友好）：composer config -g repo.packagist composer https://mirrors.tuna.tsinghua.edu.cn/composer/

php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！