必须配全局镜像且三要素缺一不可，否则 composer require 仍直连 packagist.org；常见失败原因包括配置项拼写错误、缺 type 值、URL 末尾无斜杠、sudo 配置与用户不一致等，需验证 config 输出、清缓存、-vvv 实测确认镜像生效。
必须配全局镜像，且三要素缺一不可，否则 composer require 仍直连 packagist.org，不报错但无效。
为什么 composer require 还是慢？镜像根本没生效
执行 composer require 时卡在 Downloading https://packagist.org/packages.json 或反复重试，大概率不是网络问题，而是镜像配置静默失败。常见原因：
-
repo.packagist写成repos.packagist（多一个s）→ Composer 完全忽略，不提示 - 漏掉中间的
composer参数：composer config -g repo.packagist https://mirrors.aliyun.com/composer/❌ → 缺 type 值，fallback 到官方源 - URL 末尾没斜杠：
https://mirrors.aliyun.com/composer❌ → 请求路径拼成/composerpackages.json，返回 404 - 用
sudo composer config -g配置，写入的是/root/.composer/config.json，但composer require是当前用户运行，读的是$HOME/.composer/config.json
验证镜像是否真正接管 require 流程
别信“我执行过了”，只看这三件事：
- 运行
composer config -g repo.packagist，输出必须是完整 JSON：{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}；空、null、或仍是https://packagist.org都说明失败 - 执行
composer clear-cache，否则旧packages.json仍在本地缓存，根本不发请求 - 加
-vvv实测：composer require monolog/monolog -vvv 2>&1 | grep "packages.json\|Downloading"，应看到GET https://mirrors.aliyun.com/composer/packages.json
require 后仍卡在 Downloading https://codeload.github.com/
这不是镜像没配好，而是 composer.lock 里存的还是原始 GitHub 的 dist.url。镜像只代理元数据（packages.json），不托管 ZIP 包：
-
--repository参数对已有composer.lock完全无效，它只影响元数据拉取环节 - 必须删掉
vendor/和composer.lock，再跑composer require，让 Composer 重新生成带镜像域名的dist.url - 若项目
composer.json中已定义repositories字段（哪怕值是{}或{"packagist.org": false}），全局配置会被完全屏蔽
并发下载不调，镜像等于白配
Composer 2.2+ 默认只并发 3 个连接，国内带宽严重浪费。不改这个参数，换再快的镜像也卡在 Downloading：
- 正确命令：
composer config -g http-max-concurrent-downloads 10（parallel-downloads已弃用，设了也不生效） - 搭配使用：
composer config -g prefer-dist true，强制走 ZIP 包而非--prefer-source - CI 或自动化场景建议加：
--no-dev --no-autoloader --no-scripts，进一步减少非必要开销
最易被忽略的一点：镜像同步有延迟，新发布的包可能几小时内搜不到；这时 require 报 Could not find package 不代表配置错了，而是镜像还没同步完——别急着换源，等两小时再试。
