Composer 镜像配置必须严格正确：全局配置命令为 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，三要素缺一不可；推荐项目级配置并清缓存验证。
配错一个字符，Composer 就当没这回事——不报错、不提示、照连 packagist.org。镜像不是“锦上添花”，而是国内 PHP 开发能跑起来的前提。
composer config -g repo.packagist 命令必须写对三处
这条命令只有一条正确写法：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。漏掉任意一个要素，就等于没配。
-
repo.packagist是唯一合法键名，写成repos.packagist（多 s）、packagist（少 repo.）或mirror都静默失效 - 中间的
composer是 type 值，不是可选参数；省略后 Composer 2.x 会 fallback 到官方源 - URL 必须是 HTTPS + 末尾斜杠
/，少斜杠会导致拼出/composerpackages.json，返回 404
验证是否生效：运行 composer config -g repo.packagist，输出应为完整 JSON 或纯 URL 字符串，且含 mirrors.aliyun.com。空、null 或仍显示 packagist.org，说明没写进去。
项目级配置比全局更可靠，尤其在 CI/CD 和团队协作中
全局配置容易被覆盖或权限干扰（比如宝塔用 www 用户执行，但你配的是 root 的 config），项目级配置直接写进 composer.json，拉代码即生效。
立即学习“PHP免费学习笔记（深入）”；
- 进项目根目录后运行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不加-g） - 该命令自动向
composer.json的repositories字段追加packagist条目，不覆盖已有私有源 - 若项目已有
"repositories": {}，别手动编辑 JSON——格式错一个逗号就导致composer install报错 - 确认生效后，
composer.json中应出现类似："packagist": {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
换源后仍卡在 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.packagist.org，说明 fallback 触发了，配置没起作用
最常被忽略的是缓存残留和权限错位——CI 流水线用 runner 用户，宝塔用 www 用户，它们都读不到你本地 root 的全局配置。配完不验证，等于白配。
