进阶Composer：自定义国内镜像源配置-composer-PHP中文网

composer配置镜像后仍走官方源，根本原因是项目级composer.json的repositories优先覆盖全局设置，且composer 2.2+默认启用packagist.org fallback机制；需删除或修改项目中的官方源配置、禁用fallback、确保镜像地址末尾无斜杠。

进阶composer：自定义国内镜像源配置

为什么 `composer config` 设置镜像后仍走官方源？

常见现象是执行 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 后，composer install 依然卡在 packagist.org。根本原因在于：Composer 会优先读取项目根目录下的 composer.json 中的 repositories 配置，覆盖全局设置；另外，从 Composer 2.2 开始，默认启用了 packagist.org 的「fallback」机制——即使你配置了国内镜像，它仍会悄悄尝试访问官方源做元数据校验。

检查是否项目级 composer.json 里写了 "repositories": [{"type": "composer", "url": "https://packagist.org"}]，有就删掉或改成镜像地址
禁用 fallback：运行 composer config -g repo.packagist.allow-fallback false
确认镜像地址末尾不带 /（如 https://mirrors.tuna.tsinghua.edu.cn/composer 正确，https://mirrors.tuna.tsinghua.edu.cn/composer/ 可能触发重定向失败）

如何让团队成员自动同步镜像配置？

靠每人手动执行 composer config -g 不现实，也难统一。更可靠的方式是把镜像配置写进项目级 composer.json，并配合 config.platform 或 scripts 做兜底。

在项目 composer.json 根对象下添加：

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

加一条安装前检查脚本：

"scripts": {
  "pre-install-cmd": "if ! composer config repo.packagist | grep -q 'aliyun\|tuna'; then echo '⚠️  请先配置国内镜像源'; exit 1; fi"
}

注意：项目级 repositories 会完全屏蔽 packagist.org，但若镜像临时不可用，allow-fallback false 会导致直接失败，需权衡稳定性

`composer global require` 为什么没走镜像？

全局命令（如 composer global require laravel/installer）默认不读取项目级配置，但会读全局配置——前提是全局配置存在且未被项目覆盖。问题常出在：全局 composer.json 路径被误改、权限不足导致写入失败、或用户家目录下存在 .composer/config.json 与 ~/.config/composer/config.json 两个位置（Composer 2+ 默认用后者）。

Composer

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

下载

查当前生效的全局配置路径：composer config --global --editor（会打开实际文件）

手动编辑该文件，确保 repositories 字段存在且结构正确：

{
  "repositories": {
    "packagist.org": {
      "type": "composer",
      "url": "https://mirrors.tuna.tsinghua.edu.cn/composer/"
    }
  }
}

别用 composer config -g repo.packagist 简写，它只设键值，不保证嵌套结构完整；建议直接编辑 JSON 文件

镜像源选清华还是阿里？参数和行为差异在哪？

两者都稳定，但细节不同：清华源（https://mirrors.tuna.tsinghua.edu.cn/composer/）支持完整的 Packagist 元数据同步，且响应头带 X-Mirror-Last-Update 时间戳；阿里源（https://mirrors.aliyun.com/composer/）对私有包支持更好，但偶尔出现元数据延迟（尤其新发布包）。实际影响主要在首次 composer update 的速度和准确性上。

清华源推荐搭配：composer config -g repos.packagist composer https://mirrors.tuna.tsinghua.edu.cn/composer/
阿里源若遇到 Could not parse version constraint 类错误，大概率是镜像元数据滞后，可临时切回官方源验证：composer config -g repo.packagist composer https://packagist.org
所有镜像都不代理 dist 文件下载（zip/tar.gz），只代理 metadata 查询；所以 install 时仍可能慢——这是正常设计，不是配置错误

镜像配置本身不难，真正容易被忽略的是 fallback 行为、全局 vs 项目级优先级、以及 dist 文件仍走原始 CDN 这一事实。