Composer全局换源需严格满足三要素：-g参数不可省略，键名必须为repo.packagist（单数），composer为强制type值且URL须以HTTPS结尾斜杠；缺一即静默失效，验证需输出完整JSON对象。
直接换源就能解决，但90%的人配不成功——不是网络被墙，是命令写错了三个关键点。
composer config -g repo.packagist 命令必须写对三要素
这条命令不是“大概对就行”，漏掉任意一个都会静默失效，且不报错：
-
-g不能省：缺了就只改当前项目composer.json，换目录就失效 -
repo.packagist是唯一合法键名（注意是repo单数，不是repos；也不能写成packagist.org） -
composer是type值，不是可选参数——省略后 Composer 2.0+ 会 fallback 到官方源 -
https://mirrors.aliyun.com/composer/必须用 HTTPS，且末尾斜杠/不能少（少斜杠会拼出/composerpackages.json导致 404）
正确写法：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
验证是否生效：composer config -g repo.packagist，应输出类似{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。如果返回空、null或报错，说明没写对。
立即学习“PHP免费学习笔记（深入）”；
项目级配置比全局更可靠，尤其适合团队和 CI
全局看着省事，但实际容易踩坑：
- 某些项目在
composer.json里写了"packagist.org": false，会直接屏蔽全局镜像 - CI 流水线常以
www或runner用户运行，而-g配的是当前登录用户的配置，权限不一致就失效 - 新人拉代码后行为不一致——全局配置无法被 Git 跟踪
推荐做法：进项目根目录，运行composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉-g）。它会自动在composer.json顶层写入"repositories"字段，key 固定为"packagist"，不会覆盖已有私有源——前提是原来repositories是对象结构（不是数组）。
如果项目已存在"repositories"数组，别手动覆盖，用命令追加，否则可能误删私有包源。
换源后仍卡在 “Resolving dependencies”？和镜像无关
镜像只加速下载，不解决依赖解析慢的问题。如果你发现composer update卡在Resolving dependencies几十秒甚至几分钟，基本可以确定是本地环境或composer.json写法导致的：
- PHP 版本约束太宽（如
"php": "^7.4 || ^8.0"） - 大量未锁定版本的
dev包 -
require-dev里塞了太多工具链
这类问题换任何镜像都无效，得从约束收紧、dev包拆分、锁版本入手。
换源后首次 install 报 hash 校验失败怎么办
这是常见副作用，不是配置错误：
- 删掉项目里的
vendor/目录和composer.lock文件 - 再执行
composer install（不是update）
注意：改完镜像源后，composer.lock记录的包来源和签名可能不匹配，必须重建 lock 文件才能同步新源的元数据和校验信息。
