必须换国内镜像源，否则 composer install 会因 DNS 超时、TLS 卡顿卡在 Downloading；config -g repo.packagist 易静默失败，常见原因有键名错误、缺 type 值、URL 缺尾部 /；需验证输出为完整 JSON，清缓存（composer clear-cache -v），删 vendor 和 lock 文件重装，并优先使用项目级配置确保生效。
必须换国内镜像源，否则 composer install 卡在 Downloading 是大概率事件，不是网络问题，而是默认连 packagist.org 导致 DNS 解析超时、TLS 握手卡顿、首字节延迟动辄 300ms+。
为什么 composer config -g repo.packagist 总是不生效
这条命令极易静默失败，不报错也不提示，常见原因就三个：
-
repo.packagist键名写成repos.packagist（多一个 s）——Composer 2.x+ 直接跳过，fallback 回https://packagist.org - 漏掉中间的
composertype 值：正确写法是composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，少这个单词就无效 - URL 末尾缺
/：比如https://mirrors.aliyun.com/composer❌，会拼出/composerpackages.json导致 404；正确是https://mirrors.aliyun.com/composer/✅
验证是否真写进去了：运行 composer config -g repo.packagist。输出必须是完整 JSON 对象，例如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null 或仍含 packagist.org，说明没写进去。
换源后还卡在 Downloading？先清缓存再重装
镜像只加速下载，但旧缓存里存着 packagist.org 的元数据，Composer 会优先读缓存并尝试从旧地址校验——结果就是卡在 DNS 或 TLS 握手，根本没发请求过去。
- 必须立刻执行
composer clear-cache，推荐加-v看实际删了什么：composer clear-cache -v - 如果项目已有
vendor/和composer.lock，建议一并删掉再跑：rm -rf vendor composer.lock && composer install --no-cache -
composer.lock记录的是旧源的包哈希，和镜像返回的元数据不兼容，保留它必报hash does not match
项目级配置比全局更可靠，尤其适合 CI/CD 和团队协作
全局配置（-g）在宝塔、Docker、CI 中极易因用户权限错位而失效——比如你在终端用 root 配了，但构建脚本以 www 或 runner 用户运行，根本读不到 /root/.composer/config.json。
- 进项目根目录后运行（不加
-g）：composer config repo.packagist composer https://mirrors.aliyun.com/composer/ - 该命令自动向
composer.json的repositories字段追加条目，不覆盖已有私有源 - 改完务必跑一次
composer update --lock，否则composer.lock里仍存着旧的dist.url，下载时先试境外地址，失败才 fallback
怎么确认真的走镜像了？别信 config 输出，要看日志
光跑 composer config -g repo.packagist 显示 URL 没用，得看到网络请求实际打到镜像域名才算数。
- 实测命令：
composer show monolog/monolog -vvv 2>&1 | grep "Downloading" - 或更通用：
composer install -vvv 2>&1 | grep "Downloading" - 日志里必须出现类似
mirrors.aliyun.com或mirrors.tuna.tsinghua.edu.cn的路径；如果还看到packagist.org，说明 fallback 了
最容易被忽略的是：项目级 repositories 配置会直接覆盖全局设置，且 composer config --list 和 composer config --list --global 输出可能不一致——必须对比确认实际生效的是哪个。
