composer config -g repo.packagist 配置生效需同时满足：键名严格为单数 repo.packagist、type 值显式写 composer、url 为 https 且推荐末尾带 /；任一不符即静默回退官方源，验证须输出完整 json 对象。
直接换阿里云镜像源，90% 的外网受限问题当场解决。不是所有镜像都可用，也不是所有配置方式都等效——关键在字段名、协议、路径和生效范围。
为什么 repo.packagist 不能拼成 repos.packagist 或 repositories.packagist
Composer 全局配置中，镜像源的键名是严格固定的 repo.packagist（单数，无 s）。拼错就写进配置文件的错误字段，composer install 完全无视它。
-
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/✅ 正确写法，立即生效 -
composer config -g repos.packagist ...❌ 写入无效位置，命令不报错但配置不加载 -
composer config -g repositories.packagist ...❌ 同样无效，且可能干扰后续手动添加的私有仓库
验证是否成功：运行 composer config -g repo.packagist，输出应为 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，而不是 null 或空对象。
HTTPS 是硬性要求，HTTP 镜像源会直接报 Invalid repository type
Composer 2.x 默认禁用非 HTTPS 源。哪怕你用的是旧版 Composer，阿里云、腾讯云等主流镜像也已强制 HTTPS，HTTP 地址（如 http://mirrors.aliyun.com/composer/）会触发校验失败。
- ✅ 正确地址：
https://mirrors.aliyun.com/composer/（末尾无斜杠也可，但推荐保持一致） - ❌ 错误地址：
http://mirrors.aliyun.com/composer/、https://packagist.phpcomposer.com（该站已停更，返回 cURL error 60） - ⚠️ 腾讯云镜像需带末尾斜杠：
https://mirrors.cloud.tencent.com/composer/，少斜杠会 404
如果遇到 SSL 证书错误（如 cURL error 60），优先检查系统时间是否准确、CA 证书是否过期，而非降级用 HTTP。
代理配置与镜像源冲突时，谁生效？
代理（http-proxy）和镜像源（repo.packagist）不互斥，但顺序影响实际行为：镜像源决定“去哪下”，代理决定“怎么连”。若两者同时配置，Composer 先走镜像 URL，再经代理发出请求。
- 公司内网必须走代理 + 国内镜像：先设
composer config -g http-proxy http://proxy.company.com:8080，再设repo.packagist - 误设代理却不需要：用
composer config -g --unset http-proxy清除，否则即使换了镜像也会卡在代理连接环节 - Git Bash 下 Windows 用户注意：
COMPOSER_HOME可能未生效，直接打开%APPDATA%\Composer\config.json确认内容
代理配置错误比镜像配置错误更隐蔽——它不会报“找不到包”，而是表现为超时或 Connection refused，容易误判为镜像问题。
项目级镜像覆盖全局配置，但缓存不自动刷新
项目根目录 composer.json 中的 repositories 字段优先级高于全局 repo.packagist。一旦写了，就以它为准；删掉后，Composer 不会自动回退到全局设置，而是继续尝试已缓存的旧源。
- 项目里加了私有仓库但忘了保留 packagist 条目 →
Could not find package xxx，因为默认禁用了官方源 - 删掉
repositories后仍走旧镜像 → 必须执行composer clear-cache，否则composer install仍从缓存读取旧地址 - CI/CD 中建议用项目级配置：可 Git 跟踪、环境一致；全局配置适合个人开发机，但团队协作时容易被覆盖或遗忘
最麻烦的不是配错，而是配完没验证、删完没清缓存、切源没测连通性——三个动作缺一不可。
