Composer 配置镜像源必须使用 repo.packagist 键名、composer 类型及末尾带 / 的 HTTPS URL；全局配置用 -g，项目级配置写入 composer.json 的 repositories 对象并优先生效。
composer config repo.packagist 命令必须带 type 参数和末尾斜杠
Composer 不支持“按开发者”同步镜像源，它只认 repo.packagist 这个固定键名的全局或项目级配置。所谓“特定开发者”，实际是指不同用户账户下的配置隔离——比如 CI runner、宝塔 www 用户、Docker 容器内用户，它们各自有独立的 ~/.composer/config.json。配置时漏掉 composer（即 type 值）或 URL 少了末尾 /，就会静默失效，退回到 packagist.org。
正确写法只有这一种：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
-
-g不能省：否则只写进当前项目composer.json，换目录就失效 - 键名必须是
repo.packagist（单数、小写、无 s），repos.packagist或packagist.org都无效 - 第二个参数
composer是 type 声明，不是注释，漏掉新版 Composer 直接忽略整条配置 - URL 必须以
https://开头且末尾带/，少斜杠会拼出/packages.json导致 404
验证是否真对目标用户生效，别信日志信 config 输出
运行 composer install -vvv 看到 mirrors.aliyun.com 请求日志，不代表镜像已启用——那可能是缓存残留或 fallback 行为。真正判断依据只有一条：composer config -g repo.packagist 的输出必须是完整 JSON 或明确 URL 字符串。
如果返回空、null、报错，或仍是 https://packagist.org，说明没写进去。CI 脚本开头务必加这句做断言：
composer config -g repo.packagist | grep -q "mirrors.aliyun.com" || (echo "镜像未配置" >&2; exit 1)
特别注意：在 Docker 构建、宝塔后台、GitHub Actions 中，执行命令的用户 ≠ 你本地终端用户。比如宝塔里跑 composer install，得用 sudo -u www composer config -g repo.packagist ... 才能配到真正干活的用户下。
项目级配置才是团队协作中“特定项目专属镜像”的唯一可靠方式
全局配置无法被 Git 跟踪，新人拉代码后行为不一致；而项目级配置写进 composer.json 的 repositories 字段，天然可版本化、可复现。执行命令时不加 -g：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/
但要注意两个硬性前提：
- 项目
composer.json里原本的repositories必须是对象（{}），不是数组（[]），否则命令会报错 - 配完必须删掉
vendor/和composer.lock，再跑composer install（不是update），否则旧 lock 文件仍按原元数据地址解析
项目级配置优先级高于全局，哪怕你本地配了全局，只要项目里有 repositories，就一定会走项目定义——这不是备选，而是协作一致性的强制要求。
想让某些包走私有源、其余走镜像？得手动写 repositories 数组
Composer 不支持“按开发者”路由，但支持按包名路由。比如你想让 topthink/think 走腾讯云镜像，其余走阿里云镜像，就得在 composer.json 里显式写：
"repositories": [
{
"type": "package",
"package": {
"name": "topthink/think",
"version": "8.0.0",
"dist": {
"url": "https://mirrors.cloud.tencent.com/composer/p2/topthink/think/8.0.0.0-zip-abc123.zip",
"type": "zip"
}
}
},
{
"packagist.org": false
},
{
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
}
]
顺序很重要："packagist.org": false 必须放在镜像源之前，否则它仍会作为兜底源参与请求；私有 package 类型源优先级最高，匹配到就不再往下查。
复杂点在于：这种写法没法靠 composer config 命令自动生成，必须手改 composer.json，且每次增删包都要同步维护。容易被忽略的是——一旦用了 package 类型，你就得自己维护 dist URL 和 hash，镜像同步延迟或路径变更都会直接导致安装失败。
