Composer镜像切换需分场景：composer config -g repo.packagist composer URL/管全局命令（如global require），COMPOSER_REPO_PACKAGIST_URL环境变量仅影响当前composer install的依赖解析，且须配COMPOSER_DISABLE_PACKAGIST=1禁用兜底源，二者缺一即静默回退packagist.org。
直接用环境变量切换 Composer 镜像，不是“理论上可行”，而是必须配合 composer config -g repo.packagist 和 COMPOSER_REPO_PACKAGIST_URL 两种机制分场景使用——前者管全局命令（如 composer global require），后者管项目安装（composer install），混用或漏掉任一环节都会静默回退到 packagist.org。
为什么 COMPOSER_REPO_PACKAGIST_URL 在 composer install 里才生效
这个环境变量只在依赖解析阶段被 Composer 读取一次，且仅影响当前命令的仓库地址；它不会写入任何配置文件，也不改变全局设置。典型适用场景是 CI/CD 流水线中临时切镜像：
- GitLab CI 中这样写：
COMPOSER_REPO_PACKAGIST_URL=https://mirrors.tencent.com/composer/ composer install - 必须搭配
COMPOSER_DISABLE_PACKAGIST=1，否则 packagist.org 仍会作为兜底源参与解析，拖慢速度甚至拉错包 - 不支持
${VAR}插值语法——变量名必须字面量拼写正确，且启动 PHP 进程前就得存在（docker run -e COMPOSER_REPO_PACKAGIST_URL=...） - 验证是否生效：运行
composer diagnose，输出里 “Repo packagist.org” 行应显示你设的 URL，而不是 “https://www.php.cn/link/ec811d0d775adc62776ba80fadd4ed19”
为什么 composer global require 总是连原始源
全局命令走的是 ~/.composer/config.json 的 repo.packagist 配置，完全不读环境变量。常见现象是：你设了 COMPOSER_REPO_PACKAGIST_URL，composer install 没问题，但 composer global require larastan/larastan 卡在下载 packages.json。
- 修复方式：进
~/.composer目录，执行composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/（注意中间的composer是 type 参数，不能省） - URL 必须以
/结尾，否则请求路径变成https://mirrors.aliyun.com/composerpackages.json→ 404 - Windows 用户改完要重开终端，否则
composer config -g repo.packagist查不到新值 - 验证：运行
composer global show -s，输出里 “Repository” 行应含你配的镜像域名
项目级配置如何不覆盖全局镜像又保留私有源
只要项目根目录 composer.json 里有 repositories 字段，全局 repo.packagist 就彻底失效——这是设计行为，不是 bug。想兼顾私有包和镜像，得手动构造完整仓库列表：
- 必须把
{"packagist.org": false}放在repositories数组第一个位置，显式禁用默认源 - 再追加镜像源：
{"type": "composer", "url": "https://mirrors.laravel-china.org/"} - 最后放私有源，比如：
{"type": "composer", "url": "${PRIVATE_REPO_URL}"}（注意：只有url字段支持${VAR}，type不支持） - 别用
composer config repo.packagist ...（不带-g）去写，它会全量替换整个repositories数组，清掉你已有的私有源
最易被忽略的一点：CI/CD 中多个 job 共享机器时，COMPOSER_HOME 若未隔离，composer config -g 写的全局镜像会被相互覆盖；务必用 COMPOSER_HOME=/tmp/composer-$CI_JOB_ID 临时指定，否则今天测试环境切了镜像，明天生产构建就悄悄连回 packagist.org。
