直接改composer config -g repo.packagist即可，但需严格满足三要素：键名必须是repo.packagist（单数、无s）、type值必须显式写composer、URL末尾必须带/，缺一不可；否则静默失效且不报错。
直接改 composer config -g repo.packagist 就行，但绝大多数人配不成功，不是网络问题，是命令写错——漏掉 composer 类型声明、多写一个 s 变成 repos.packagist、URL 缺末尾斜杠，这三处错任意一个，都不生效，还不报错。
为什么 composer config -g repos.packagist 无效？
因为键名必须是 repo.packagist（单数 repo），不是 repos.packagist（复数 repos）。官方文档里写的是 repo.packagist，Composer 内部硬编码识别这个 key。写成 repos 后，配置会静默写入一个无用字段，composer config -g repo.packagist 查出来是空或 null，install/update 仍走官方源。
验证方式很简单：
- 运行 composer config -g repo.packagist
- 正确输出应为类似：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
- 如果返回空、null 或报错，说明没写对。
composer config -g repo.packagist 命令必须带的三个参数
这条命令完整结构是：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。缺一不可：
-
-g：表示全局配置，影响所有项目 -
repo.packagist：配置项 key，不能拼错、不能加 s、不能大小写混用 -
composer：这是type值，不是可选参数，也不是注释——省略它，Composer 2.0+ 会 fallback 到默认源，等于白配 -
https://mirrors.aliyun.com/composer/：URL 必须用 HTTPS，且末尾必须有/，否则请求路径会拼错（如变成.../composerpackages.json），直接 404
项目级配置比全局更可靠
全局配置看着省事，但一旦你参与多个项目（比如开源库 + 公司内部系统），就容易出问题：
- 某些项目在
composer.json里硬写了"repositories": {"packagist.org": false}或空数组，会覆盖全局设置 - CI 流水线里如果混用不同镜像，可能导致
composer.lockhash 不一致，引发部署失败 - 团队协作时，全局配置无法被 Git 跟踪，新人拉代码后行为不一致
推荐做法：进项目根目录，运行composer config repo.packagist composer https://mirrors.aliyun.com/composer/
（注意：去掉 -g）
它会自动在 composer.json 顶层写入 "repositories" 字段，key 固定为 "packagist"，不会覆盖已有私有源——只要原来 repositories 是对象（不是数组），命令就会安全合并。
换源后依然卡在 Resolving dependencies？和镜像无关
镜像只加速包下载（Downloading 阶段），不解决依赖解析慢的问题。如果你发现 composer update 卡在 Resolving dependencies 几十秒以上，基本可以确定是本地环境或 composer.json 写法导致的：
- PHP 版本约束太宽，比如
"php": "^7.4 || ^8.0 || ^8.1"，让 Composer 要遍历更多版本组合 -
require-dev里塞了太多未锁定版本的工具链（如"phpunit/phpunit": "^9"而不是"^9.6"） - 项目用了大量
dev-main或dev-develop分支依赖，每次都要重新 fetch 元数据
这时候切镜像源毫无作用，得去收紧版本约束、删掉冗余 dev 包，或者用 composer update --with-dependencies 配合 --dry-run 排查瓶颈点。
最容易被忽略的一点：换源后一定要跑 composer clear-cache。Composer 会缓存旧源的 packages.json 和包元数据，不清缓存，它可能还在用过期的官方源索引做解析，导致 install 看似走镜像，实则解析逻辑还是旧的。
