composer config -g repo.packagist 命令需严格满足三条件才生效：键名必须为单数 repo.packagist（非复数）、中间 composer 为必需 type 值、url 必须带 https:// 且末尾含 /；否则静默回退至官方源，不报错也不提示。
Composer require 无法下载，不是网络问题，而是镜像没配对或缓存/锁文件残留——换源本身不能跳过这三步：写对配置、清掉缓存、删掉 lock 文件。
composer config -g repo.packagist 命令为什么总不生效
这条命令写错任意一个字符都会静默 fallback 到 https://packagist.org，不报错也不提示。必须同时满足：
-
repo.packagist是固定键名（单数、全小写、无 s），写成repos.packagist或repositories.packagist.org都无效 - 中间的
composer是必需的type值，不能省略，也不能替换成https或其他字符串 -
URL必须是 HTTPS 且末尾带/：https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（少斜杠会导致请求路径拼成/composerpackages.json，直接 404）
换源后依然卡在 Downloading https://api.github.com/
中文镜像只代理元数据（packages.json），不托管实际 zip 包。Composer 仍会从 GitHub 拉取 dist 文件，这才是卡顿主因。
-
composer.lock里固化的是原始dist.url，哪怕镜像已生效，composer install仍会照着旧地址去下载 - 日志中看到
Downloading https://api.github.com/或https://codeload.github.com/，说明 zip 路径没被替换 - 临时加
--repository-url只影响元数据获取，对 lock 文件里的dist.url完全无效
验证是否真走镜像，别信配置输出
配置存在 ≠ 当前正在用它。真正证据是网络请求日志：
- 运行
composer config -g repo.packagist，输出必须是完整 JSON 对象，例如：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}；返回空、null或https://packagist.org，说明根本没写进去 - 执行
composer install -vvv，观察日志中Reading packages.json from cache at /https---mirrors-aliyun-com-composer/这类路径 —— 出现才代表真走了镜像 - 若仍看到
GET https://packagist.org/packages.json，立刻检查项目级repositories字段是否覆盖了全局配置
删 vendor 和 composer.lock 不是可选动作，是必做步骤
旧 composer.lock 里的 hash 和 dist URL 来自官方源，和镜像元数据不匹配会导致校验失败、404 或 “Package not found”。
- 必须执行：
rm -rf vendor composer.lock（Linux/macOS）或手动删除（Windows） - 再跑
composer install，才能让 Composer 重新解析依赖、生成新 lock 文件、走镜像拉取元数据，并从正确位置下载 dist - 如果项目有 CI 流水线，务必在脚本中加入这两步，否则每次构建都可能复现失败
最常被忽略的是：镜像只解决元数据加载慢，不解决 GitHub 下载慢；而 composer.lock 一旦固化原始 dist 地址，就彻底绕过了镜像能力——删 lock 是唯一能重置它的操作。
