Composer镜像配置不生效的三大原因是：键名必须为repo.packagist（单数）、第二参数必须显式写composer、URL须HTTPS且末尾带/；任一错误即静默回退官方源，验证需输出完整JSON对象。
镜像源配错，90% 的人根本没生效——不是 Composer 不快，是你连元数据都没拉下来。
composer config -g repo.packagist 为什么总不生效
它不报错，但写错一个字符就静默回退到 packagist.org。关键就三点：
- 键名必须是
repo.packagist（单数，repos.packagist或repository.packagist都无效） - 第二参数必须是字符串
composer，不能省略、不能写成type或git -
url必须以https://开头，且末尾带/，比如https://mirrors.tencent.com/composer/；少斜杠会触发Could not parse version constraint
验证唯一方式：composer config -g repo.packagist。✅ 正确输出是完整 JSON：{"type": "composer", "url": "https://mirrors.tencent.com/composer/"}；❌ 输出为空、null、https://packagist.org 或报错，说明完全没生效。
composer create-project 还卡在 packages.json？那是没走镜像
这个命令分两步：先从 GitHub 克隆 skeleton（不走 Composer 镜像），再进目录执行 composer install（才走 repo.packagist）。所以你看到卡在 Downloading https://packagist.org/packages.json，说明第二步根本没启动——第一步就卡死了。
- 第一步卡住（
Cloning Laravel repository）：大概率是 GitHub API 限流，要配composer config -g github-oauth.github.com <your_token> - 第二步仍卡：确认
composer config -g repo.packagist已正确输出，再加-vvv看日志里是否出现GET https://mirrors.tencent.com/composer/packages.json - 更稳做法：直接加
--repository参数，强制整个流程走镜像：composer create-project laravel/laravel myapp --repository=https://mirrors.tencent.com/composer/
项目级 repositories 怎么写才不冲突
全局配置会被项目级 repositories 完全覆盖，且顺序即优先级。混用私有包和公共镜像时，结构必须严格：
- 键名是复数
repositories（不是repo.packagist），放在composer.json顶层 - 私有源放前面，
"packagist": false写在根节点（不是塞进数组里），再跟镜像源 - 每个源的
type必须是composer，URL 末尾必须带/
示例（阿里云镜像 + 私有包）：
{
"name": "laravel/laravel",
"repositories": [
{
"type": "composer",
"url": "https://packages.mycorp.com/"
},
{
"packagist": false
}
],
"repositories": {
"packagist": {
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
}
}
}
改完必须删掉 composer.lock，再跑 composer install，否则旧 lock 文件仍走历史源。
缓存路径没设，镜像再快也白搭
只换源不开缓存，每次都要重下 ZIP 包；只开缓存不换源，缓存根本拉不到包。二者必须配对：
- 启用缓存路径：
composer config -g cache-files-dir ~/.composer/cache/files（若输出为空，说明未启用） - 设缓存有效期防误用：
composer config -g cache-files-ttl 3600 - 验证是否真走缓存：删掉
vendor/后跑composer install -vvv，看日志是否有Cache hit或Using cached
CI/CD 或团队协作时，别把镜像写进 composer.json —— 项目级 repositories 会强制所有成员走同一源，在跨地域或 CI 环境里极易出问题。全局配置 + 缓存 + 参数控制，才是稳定组合。
