配镜像必须一步到位：键名必须为repo.packagist（单数），type值必须为小写composer且不可省略，URL须HTTPS且末尾带/；项目级配置比全局更可靠，需删vendor和lock后重装。
配镜像不是“试试看”，而是必须一步到位——漏掉 repo.packagist 的任意一个字符、少写 composer 这个 type 值、URL 末尾缺 /，都会静默失败，你看到的仍是 packagist.org。
为什么 composer config -g repo.packagist 看似执行成功却没用
它不报错，也不提示，但 composer install 还在连 packagist.org。根本原因就三个硬性条件没对齐：
-
repo.packagist是唯一合法键名（注意是repo单数，不是repos或repository） - 第二个参数
composer是type值，小写，不可省略，也不能写成package或composer.org - URL 必须是 HTTPS 且末尾带
/：比如https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（少斜杠会导致请求路径拼成/composerpackages.json，404）
验证是否真写进去了？别信命令输出，直接运行：composer config -g repo.packagist。输出必须是完整 JSON，例如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null、或仍显示 packagist.org，说明根本没写成功。
项目级配置比全局更可靠，尤其在 CI/CD 和宝塔里
你在终端配好全局镜像，但 GitHub Actions、宝塔后台、Docker 容器里的 composer 根本读不到你的 ~/.composer/config.json——因为它们用的是 runner、www 或容器内用户，不是你。
进项目根目录（确保有 composer.json），执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉 -g）。
- 这条命令会自动在
composer.json顶层写入"repositories"字段，key 固定为"packagist" - 如果项目已有
"repositories": []（数组形式），命令会报错；需先手动改成"repositories": {}（空对象）再重试 - 改完必须删掉
vendor/和composer.lock，再跑composer install（不是update）
换源后还是卡在 “Resolving dependencies” 或 “Loading composer repositories”
镜像只加速下载环节，不参与依赖解析。卡点可能完全不在镜像上：
-
Resolving dependencies卡住？这是 Composer 在本地穷举版本组合，和镜像无关。检查composer.json里有没有宽泛约束如"php": "^7.4 || ^8.0"或大量dev-main依赖 -
Loading composer repositories卡住？说明旧缓存还在起作用。必须执行：composer clear-cache，再删vendor/和composer.lock - 宝塔环境卡住？先确认 PHP CLI 是否禁用了
proc_open、putenv、pcntl_signal——这些函数被禁用时，Composer 启动即崩溃，根本走不到镜像环节
临时验证镜像是否可用，不用改任何配置
不想动全局或项目配置，又想快速测试某个镜像地址是否通？加 --repository-url 参数：
composer install --repository-url=https://mirrors.aliyun.com/composer/
这个参数优先级最高，会覆盖全局和项目级配置，适合调试或 CI 脚本中一次性指定。但注意：composer create-project 不支持 -r 或 --repository-url，CI 中必须先 config -g 再执行。
真正容易被忽略的点是：哪怕命令执行成功，只要 composer.json 里存在 repositories 字段（哪怕只是空数组），全局配置就会被跳过，且不警告、不提示——你得自己去查 composer config -l | grep repositories 或打开文件确认。
