必须配对、配全、配准三要素：键名repo.packagist（单数）、type值composer、URL为HTTPS且末尾带/，缺一则静默回退官方源；验证需输出完整JSON，项目级配置更可靠，换源后须执行composer clear-cache并重装。
换镜像不是“试试看”，而是必须做的第一步，且必须配对、配全、配准——错一个字符，Composer 就静默 fallback 到 packagist.org，不报错、不提示、不警告。
composer config -g repo.packagist 命令必须写对三处
这条命令是全局换源的唯一合法入口，但极易因拼写或格式错误完全失效：
-
repo.packagist是唯一合法键名；repos.packagist（多一个 s）、mirror、packagist都无效 - 中间的
composer是type值，缺了它，Composer 2.x 会直接忽略配置，回退到默认源 - URL 必须是 HTTPS + 末尾带
/：https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（少斜杠会导致路径拼接错误，返回 404）
验证是否生效：运行 composer config -g repo.packagist，输出必须是完整 URL 字符串或 JSON 对象（含 "url": "https://..."），空、null 或仍显示 https://packagist.org 说明没写进去。
项目级配置比全局更可靠，尤其在 CI/CD 和团队协作中
进项目根目录后执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉 -g）
立即学习“PHP免费学习笔记（深入）”；
该命令会自动向 composer.json 的 repositories 字段追加 packagist 条目，不覆盖已有私有源。优势在于：
- 配置随代码提交，新人拉完即用，行为一致
- CI 构建时无需额外 setup，每次都会读取最新设置
- 避免全局配置被不同用户、不同项目或宝塔等面板覆盖（比如 www 用户执行 vs root 配置）
若项目已有 "repositories": {}，别手动编辑 JSON——格式错一个逗号就导致 composer install 报错；务必用命令追加。
换源后仍卡在 Downloading？先清缓存再重装
镜像只加速下载，但旧缓存里存着 packagist.org 的元数据，Composer 会优先读缓存并尝试从旧地址校验，结果就是卡在 DNS 或 TLS 握手——不是没走镜像，是根本没发请求过去。
必须执行：
composer clear-cache- 删掉
vendor/和composer.lock - 再跑：
composer install --no-cache（禁用缓存强制走新源）
别试图保留旧 composer.lock——它记录的是旧源的包哈希，和镜像返回的元数据不兼容，必然报 hash does not match。
验证是否真走镜像，不能只看 config 输出
光跑 composer config -g repo.packagist 显示 URL 没用，得看到网络请求实际打到镜像域名才算数。
实测命令：composer show monolog/monolog -vvv 2>&1 | grep "Downloading"
日志里必须出现 mirrors.aliyun.com 或 mirrors.cloud.tencent.com 等镜像域名；如果看到 https://packagist.org 或 repo.packagi（截断），说明镜像根本没生效。
真正容易被忽略的是：换源只是解决下载慢，不解决 Resolving dependencies 卡顿——那通常是 PHP 内存不足、Xdebug 启用中、platform 配置错位或 composer.lock 残留已下线包导致的，得另查。
