Composer中文镜像配置失败怎么办（排查思路）-composer-PHP中文网

新项目仍走官方源，大概率因项目级配置覆盖全局配置；composer优先级为项目composer.json > 全局config.json；需用composer config --list -g和composer config --list分别验证全局与项目级设置是否被覆盖。

composer中文镜像配置失败怎么办（排查思路）

为什么 `composer config -g repo.packagist` 不生效

执行完这条命令后，新项目依然走官方源，大概率是因为全局配置被项目级配置覆盖了。Composer 的配置优先级是：项目根目录的 composer.json > 当前用户家目录的 auth.json 和 config.json > 系统级配置。先运行 composer config --list -g 确认全局配置里是否真写入了镜像地址；再进到项目目录下执行 composer config --list（不加 -g），看 repo.packagist 是否被重写为 https://packagist.org 或空值。

常见诱因包括：
• 项目里 composer.json 中手动写了 "repositories": [{"type": "composer", "url": "https://packagist.org"}]
• 运行过 composer config repo.packagist https://packagist.org（没加 -g，只改了当前项目）
• 使用了某些 IDE 插件或 CI 脚本，在构建时强制重置源

阿里云、腾讯云、华为云镜像地址现在还能用吗

2024 年起，主流中文镜像已陆续停用或限流：阿里云镜像（https://mirrors.aliyun.com/composer/）已下线；腾讯云镜像（https://mirrors.cloud.tencent.com/composer/）返回 403；华为云镜像需登录账号并绑定实名，且仅对白名单 IP 开放。目前稳定可用的是 https://packagist.phpcomposer.com（由 Laravel China 社区维护，非官方但持续更新），以及清华大学镜像（https://packagist.mirrors.tuna.tsinghua.edu.cn），后者要求在 URL 末尾加 /packages.json 才能被 Composer 正确识别。

验证方式：直接浏览器访问该 URL，应返回 JSON 格式的包索引，而不是 404 或重定向页。

使用 `composer config` 配置镜像时的参数陷阱

最容易出错的是协议和路径拼写——比如把 https://packagist.mirrors.tuna.tsinghua.edu.cn 写成 https://mirrors.tuna.tsinghua.edu.cn/packagist，少了一级路径或顺序颠倒，会导致 composer install 报错 Could not parse version constraint 或卡在 “Loading composer repositories” 阶段。

Composer

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

下载

正确写法只有两种：

全局设置（推荐）：composer config -g repo.packagist composer https://packagist.mirrors.tuna.tsinghua.edu.cn
临时切换（调试用）：composer create-project laravel/laravel demo --repository=https://packagist.mirrors.tuna.tsinghua.edu.cn

注意：composer config -g repo.packagist 后面必须跟 composer 类型标识，不能省略；清华源末尾不加斜杠，否则部分版本会解析失败。

CI/CD 环境下镜像配置失效的典型表现

GitHub Actions、GitLab CI 中跑 composer install 时仍超时，往往不是配置没生效，而是 CI runner 每次都是干净环境，没加载你的全局 config.json。这时候硬写 composer config -g 也没用——因为 runner 是无状态的。

解决办法只有两个：

在 CI 脚本开头显式设置：composer config -g repo.packagist composer https://packagist.mirrors.tuna.tsinghua.edu.cn
或更稳妥地，在 composer.json 里声明仓库（注意不是覆盖，而是追加）：
```
"repositories": [
  {
    "type": "composer",
    "url": "https://packagist.mirrors.tuna.tsinghua.edu.cn"
  }
]
```
然后确保 "packagist.org": false 关闭默认源，否则 Composer 仍会尝试连接官方源做校验

镜像配置本身很简单，真正麻烦的是不同上下文下的配置继承关系和缓存残留——删掉 ~/.composer/cache/ 有时比改配置更管用。