正确做法是将私有源置于repositories数组最前，确保其packages.json含provider-includes字段，并在末尾单独添加{"packagist.org": false}作为终止符；URL末尾必须带/，否则404导致跳过。
repositories数组顺序错乱导致私有源失效
Composer查包时不是简单按顺序发请求，而是逐个检查每个仓库的packages.json是否声明支持目标包。如果阿里云镜像排在私有Satis源前面，而镜像返回{"packages":{}}（即不包含你的私有包），Composer会直接跳过私有源——根本不会发起HTTP请求。
正确做法是把私有源放在repositories数组最前面，并确保其packages.json含完整provider-includes字段；再加一行{"packagist.org": false}作为终止符，且必须独立成项、放在数组末尾。
- 不能写成
"repositories": [{"type":"composer","url":"https://private.example.com","packagist.org":false}]——packagist.org必须是单独对象 - 私有源URL末尾必须带
/，否则packages.json路径404，Composer判定“不支持”后直接跳过 - 验证是否生效：运行
composer config repositories，输出必须是你手动写的完整数组，不能含https://repo.packagist.org
项目级配置覆盖全局但格式不兼容
只要项目composer.json里出现"repositories"字段，全局配置（如~/.composer/config.json）就会被彻底丢弃，不是合并，是整块替换。很多人用composer config -g repo.packagist ...设了全局镜像，却在项目里写"repositories": []，结果实际走的是空数组+隐式packagist.org。
项目级配置要显式声明镜像，且字段名必须是repositories.packagist.org（Composer 2.2+），不是repo.packagist或repos.packagist。漏掉.org或少一个s都会静默失败。
- 正确命令分两行：
composer config -g repositories.packagist.org.type composer+composer config -g repositories.packagist.org.url https://mirrors.aliyun.com/composer/ - 验证：
composer config -g repositories.packagist.org.url必须输出完整URL，末尾/不能少 - CI中务必重复执行这两条命令，不能依赖runner预装的全局配置
GitLab CI里残留配置引发环境不一致
CI runner可能复用之前job留下的全局配置，比如~/.composer/config.json里还存着旧镜像，或者COMPOSER_HOME指向错误路径。这时候即使项目composer.json写了新镜像，Composer仍会优先读全局配置，造成环境和本地不一致。
关键不是换镜像，而是切断所有外部继承。在.gitlab-ci.yml里必须显式清理：
-
composer config --global --unset repos.packagist（注意是repos，不是repo） -
composer config --unset repos.packagist（清项目级可能存在的覆盖） -
composer config repositories.packagist.org composer https://mirrors.aliyun.com/composer/（强制唯一源）
漏掉任意一条，都可能导致CI卡在Resolving dependencies...——它其实在反复尝试降级包来适配PHP版本差异，而不是网络慢。
镜像同步延迟与lock文件哈希错位
阿里云镜像通常有10–30分钟同步延迟，尤其对新tag或dev分支。如果你刚推送了一个包，立刻切回镜像并跑composer install，composer.lock里记录的dist.sha256还是旧值，而镜像已返回新包，必然触发checksum mismatch。
这不是配置冲突，是时间差导致的信任链断裂。此时删vendor/没用，必须连composer.lock一起删，再用composer update重建。
- 别在同步中途硬切镜像；验证是否就绪：先
composer clear-cache && composer install --no-install，看能否秒拉packages.json - CI中建议固定镜像源并缓存
packages.json，避免每次构建都撞上同步窗口期 - 若急需，换华为云镜像（
https://repo.huaweicloud.com/repository/php/），已知同步更快
真正容易被忽略的是：哪怕你把所有配置都调对了，只要composer.json里"php": "^8.1"和CI用的PHP 8.0不一致，Composer就会陷入无限回溯——它不是卡在网络，是在找一个根本不存在的版本交集。
