必须用composer config --global命令修改全局镜像，手动编辑config.json因缺少type值、URL末尾斜杠或键名错误而被静默忽略；正确格式为composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。
直接改 config.json 文件几乎必然出错——Composer 不读你手写的 JSON，它只认 composer config --global 命令写入的结构，且必须满足三要素：键名、type 值、URL 斜杠缺一不可。
为什么手动编辑 ~/.composer/config.json 失效
很多人打开 ~/.composer/config.json，把 "repo.packagist" 字段改成自己的 URL，保存后运行 composer install 却仍连 packagist.org。根本原因不是路径错、不是权限问题，而是 Composer 启动时根本不解析这个字段——除非它是由 composer config --global 命令生成的，并带完整结构。
- 手动添加的
"repo.packagist"如果没包含"type": "composer"，会被忽略（静默跳过） - URL 少了末尾
/，比如写成"https://mirrors.aliyun.com/composer"，Composer 会拼出错误路径/composerpackages.json→ 404 - 键名写成
repos.packagist（多一个s）或packagist（少repo.），字段会被存进配置但完全不识别 - JSON 格式稍有瑕疵（如多逗号、单引号、BOM 头），
composer config --global --list可能报错或返回空
composer config -g repo.packagist 的三个强制参数
这条命令不是“可选组合”，而是硬性接口契约：
-
-g（或--global）：必须显式声明，否则写入当前项目composer.json的repositories字段，和全局无关 -
repo.packagist：固定键名，大小写敏感，不能加s、不能去repo.、不能替换成mirror等别名 -
composer https://mirrors.aliyun.com/composer/：第二个参数是type值（字符串"composer"），第三个才是 URL；URL 必须以/结尾，且必须是 HTTPS（HTTP 在 Composer 2.2+ 被默认拒绝）
正确示例：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
错误示例：composer config -g repos.packagist https://mirrors.aliyun.com/composer（多 s + 少 type + 少 /）
验证是否真生效，别信 config --list 输出
composer config -g repo.packagist 返回 {"type": "composer", "url": "..."} 只说明配置写对了，不代表运行时就走这个源。真正生效要过三关：
- 检查是否被项目级覆盖：进项目目录，运行
composer config --list | grep repositories，若有输出，说明项目composer.json里写了repositories，全局配置自动失效 - 确认缓存已清：旧缓存可能含官方源的
packages.json索引，执行composer clear-cache是必要步骤 - 看真实请求域名：运行
composer install -vvv 2>&1 | grep "Downloading"，输出中第一个非github.com的域名必须是你的镜像地址（如mirrors.aliyun.com）
项目级配置比全局更可控，但要注意写法
团队协作或混合源场景下，项目级配置反而更可靠，但必须用命令写，不要手改 composer.json：
- 进项目根目录，运行
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉-g） - 它会在
composer.json顶层生成"repositories"字段，值为数组：[{"packagist": {"type": "composer", "url": "..."}}] - 如果原
composer.json已有repositories，该命令会合并而非覆盖——前提是原字段是对象（不是空数组或false） - 若已有
"repositories": {"packagist.org": false}这类禁用项，先运行composer config --unset repositories清掉再重设
最后提醒一句：Composer 的镜像逻辑不 fallback。你配了阿里云，它就不会在失败后自动试腾讯云或官方源——除非你手动写死两个源并按顺序排列，而这本身又带来 lock 文件不稳定风险。
