composer config -g repo.packagist 总不生效是因为键名必须为单数repo.packagist、type值必填composer、url须https且末尾带/，三者缺一即静默回退官方源；验证需输出完整json，项目级配置更可靠。
composer config -g repo.packagist 为什么总不生效
命令写错任意一处，就静默失败：不报错、不提示、composer install照常卡在 Loading composer repositories。最常见三处硬伤：
• repo.packagist 写成 repos.packagist（多一个 s，完全无效）
• 漏掉 composer 这个 type 值，正确写法是 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
• URL 缺 HTTPS 或末尾斜杠，比如 https://mirrors.aliyun.com/composer → 请求会拼成 /composerpackages.json，直接 404
验证是否真写进去了：composer config -g repo.packagist，输出必须是类似 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
全局配置 vs 项目级配置，该用哪个
全局配置（composer config -g）写入当前用户的 ~/.composer/config.json，但实际运行 Composer 的用户未必是当前 shell 用户——比如宝塔面板里是 www 用户，CI 流水线可能是 runner 用户。
项目级配置更稳妥：
• 进项目根目录，执行 composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉 -g）
• 它会安全写入 composer.json 的 repositories 字段，不覆盖已有私有源
• 不依赖用户 HOME 目录，Git 可追踪，团队协作行为一致
• 若项目已有 "repositories": {} 或 "packagist.org": false，先 composer config --unset repositories 清掉再配
换源后仍卡在 Downloading 或 Connection timed out
不是网络差，是镜像根本没走起来。必须同步做三件事：
• 执行 composer clear-cache：否则 Composer 优先读本地缓存的 packages.json，压根不发请求
• 检查 composer.json 是否含 "prefer-source": true，它会强制走 Git 而非 ZIP，绕过镜像加速
• 确认没硬编码 GitHub URL，比如 "dist": {"url": "https://github.com/xxx/yyy/archive/..."}，这类地址不走镜像，触发 GithubRateLimitException 就是它
顺手跑一遍 composer diagnose，如果报 Repo is not configured properly，说明 packagist.org 自动代理没关干净，补一句 composer config -g repos.packagist false 再加镜像
parallel-downloads 设多少才真有用
parallel-downloads 是 Composer 2.2+ 原生机制，只对 composer install 有效，composer update 仍串行算依赖图。
默认值是 3，基本等于没开：
• 推荐设为 10：composer config -g parallel-downloads 10
• 别盲目冲到 20：低配 CI 或企业内网容易触发 file_put_contents(): failed to open stream（临时文件竞争），降到 6–8 更稳
• 这个参数依赖镜像支持 HTTP/2 多路复用；阿里云、腾讯云、清华镜像都支持，私有源若不支持，设高了也白搭
运行 composer --version 确认 ≥ 2.2，否则先 composer self-update
clear-cache、写错 key 名、忽略用户上下文，三者任一缺失，镜像就形同虚设。
