composer config -g repo.packagist 命令直接向 ~/.composer/config.json 写入硬编码识别的 {"type": "composer", "url": "https://..."} 键值对，键名必须为单数 repo.packagist，缺 composer 类型或 URL 末尾缺 / 均静默失效。
composer config -g repo.packagist 命令到底干了什么
它不是“改配置”，而是直接向 ~/.composer/config.json 写入一个硬编码识别的键值对。Composer 2.x+ 在启动时会强制查找 repo.packagist 这个字段（注意是单数 repo，不是 repos），且只认这个 key——写成 repos.packagist 或 packagist.org 都会被忽略，不报错也不生效。
这个字段必须是完整 JSON 对象，包含 "type": "composer" 和以 / 结尾的 HTTPS URL。漏掉 composer 类型参数，Composer 就当它不存在，继续 fallback 到官方源；URL 缺末尾 /，请求路径会拼成 /composerpackages.json，直接 404。
-
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/是唯一能触发镜像生效的写法 - 执行后检查：运行
composer config -g repo.packagist，输出应为{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} - 如果返回空、
null或"https://packagist.org"，说明根本没写进去，不是网络问题，是命令错了
脚手架工具里自动注入镜像的常见实现方式
所谓“自动注入”，99% 是在脚手架的初始化逻辑里执行一条 shell 命令，而不是解析或修改 JSON 文件。比如 Laravel 官方安装器、ThinkPHP CLI 或自研脚手架，通常会在 create-project 后、composer install 前插入：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
但这里埋了三个坑：
立即学习“PHP免费学习笔记（深入）”；
- 没加
-g→ 只改当前目录下的composer.json，对后续命令无效 - 用
exec()调用却没捕获 stderr → 拼写错误（如repos.packagist）静默失败，开发者完全不知道 - 没验证执行结果 → 即使命令返回 0，
composer config -g repo.packagist输出仍可能是空，得二次检查
真正健壮的做法是：执行命令后立即调用 composer config -g repo.packagist，匹配 JSON 结构或非空字符串，否则 abort 并提示具体失败原因。
项目级 repositories 合并逻辑容易被误读
脚手架如果选择写入项目 composer.json（即去掉 -g），它调用的是 composer config repo.packagist composer ...，这个命令的行为取决于原有 repositories 字段的结构：
- 原字段是对象：
"repositories": {}→ 安全 merge，新增"packagist"子项 - 原字段是数组：
"repositories": []→ 命令直接报错，不会覆盖也不会追加 - 原字段已含私有源（如
"my-private": {"type": "composer", "url": "..."}）→ 新增的packagist会并列存在，没问题
但很多人手动编辑时习惯写成 "repositories": [{"packagist.org": false}]，这种数组格式无法被 composer config 命令安全处理，必须先转成对象格式再操作。
为什么 CI 环境里脚手架注入的镜像经常失效
不是镜像地址挂了，而是权限和用户上下文错位。典型场景：
- 宝塔面板用
www用户执行 PHP CLI 命令，但composer config -g写的是root的~/.composer/config.json - GitHub Actions 或 GitLab CI 中未指定
COMPOSER_HOME，导致composer config -g写入临时路径，下个 job 步骤就丢失 - Docker 构建中，
composer config -g执行在构建阶段，但运行时容器用户不同，~/.composer不共享
解决办法只有一个：CI 场景下放弃全局配置，改用 --repository-url 参数。例如：
composer install --no-interaction --repository-url=https://mirrors.aliyun.com/composer/ -vvv
-vvv 必须带上，否则你看不到真实请求地址，无法确认是否真走镜像。
最麻烦的不是命令写不对，而是你以为它生效了——因为 composer install 依然能跑通，只是悄悄 fallback 回了官方源。验证必须落到 composer config -g repo.packagist 的输出和 -vvv 日志里的 GET 请求路径上。
