命令composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/必须严格满足：无多余"s"、含type值"composer"、URL为HTTPS且末尾带"/"，否则配置静默失效；验证需composer config -g repo.packagist输出完整JSON；项目级配置更可靠，CI等场景应改项目级并清缓存重装。
composer config -g repo.packagist 命令写错就等于没配
国内开发者最常卡在这一步：命令看似执行成功，但composer install日志里仍出现packagist.org域名，下载卡在Downloading或直接403。根本原因不是网络差，而是composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/漏了任意一个硬性条件：
-
repo.packagist不能写成repos.packagist（多一个s就静默忽略） - 中间的
composer是type值，不是可选参数——缺了它，Composer 2.x 会自动fallback到官方源 - URL必须用HTTPS且末尾带
/：https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（少斜杠会导致拼出/composerpackages.json，返回404）
验证是否真生效，只看这一条：composer config -g repo.packagist。输出必须是类似{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}的完整JSON对象。空、null、或还是https://packagist.org，说明配置没落进去。
微服务组件安装慢，90% 和镜像无关
当你运行composer require hyperf/service-governance或composer create-project hyperf/hyperf-skeleton时，如果卡在Resolving dependencies几十秒甚至几分钟，别急着换镜像——这个阶段完全不走网络，是Composer在本地穷举满足所有约束的版本组合。
- PHP版本约束太宽（如
"php": "^7.4 || ^8.0"）会让求解器尝试大量无效组合 - 项目里写了
"minimum-stability": "dev"或大量"dev-main"依赖，极大增加解析复杂度 - 启用了
xdebug扩展（尤其在CLI模式下），会拖慢整个依赖解析过程 -
composer.json里混入大量未锁定的require-dev工具（如phpstan/phpstan、friendsofphp/php-cs-fixer），它们也会参与求解
解决办法：临时禁用xdebug（php -d zend_extension= -d extension= composer require ...）、收紧PHP平台约束、删掉不必要的dev依赖再试。
立即学习“PHP免费学习笔记（深入）”；
项目级配置比全局更可靠，尤其对微服务集群
你在本地composer config -g配好了阿里云镜像，但CI流水线跑composer install时依然超时？因为CI容器、宝塔后台、Docker部署默认以www或runner用户运行，读的是/home/www/.composer/config.json，根本看不到你root用户的全局配置。
- 进微服务项目根目录（含
composer.json），运行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉-g） - 这条命令会安全追加到
composer.json的repositories字段，不覆盖已有私有源，且能提交到Git，团队拉代码即生效 - 如果项目已存在
"repositories": []（数组格式），命令会报错；需先手动改成"repositories": {}（对象格式）再执行 - 切记：改完立刻删掉
vendor/和composer.lock，再跑composer install——旧lock文件里的哈希值和镜像元数据不匹配，会导致hash does not match错误
换镜像后仍卡住，先清缓存再重装
即使命令写对、composer config -g repo.packagist也显示正确，composer install还是慢或失败，大概率是缓存残留。Composer会优先读本地缓存里的packages.json和元数据，哪怕配置已改，它仍试图从旧地址拉校验信息。
- 必须执行：
composer clear-cache，清掉~/.composer/cache/下的全部内容 - 确认
composer.json里没有硬编码GitHub URL（如老旧dist.url），否则会触发GithubRateLimitException；需配Token：composer config -g github-oauth.github.com your_token_here - 某些企业防火墙会拦截
mirrors.前缀的HTTPS域名，若报SSL错误，换清华源试试：https://mirrors.tuna.tsinghua.edu.cn/composer/（路径结构不同，有时能绕过拦截）
微服务组件往往依赖链深、包体积大，镜像配置只是第一步；真正卡点常藏在缓存、本地求解逻辑或权限隔离里，盯着日志里出现的域名和阶段，才能精准下手。
