COMPOSER_REPO_PACKAGIST_URL仅在composer install/update时生效，global命令需手动config -g配置；CI中需同时设置环境变量和全局配置，并确保URL以/结尾、禁用packagist兜底。
CI 中 Composer 镜像变量不生效，不是配置写错了，而是没进对作用域——COMPOSER_REPO_PACKAGIST_URL 只在 composer install 运行时起作用，而 composer global require 完全不认它。
为什么 COMPOSER_REPO_PACKAGIST_URL 在 CI 里经常“看起来没用”
这个环境变量只被 composer install（或 update）在解析依赖阶段读取一次，且仅影响当前命令的源地址。它不会写入配置、不改全局设置、也不触发任何自动 fallback。
- 漏设
COMPOSER_DISABLE_PACKAGIST=1：packagist.org 会作为兜底源参与请求，导致慢、超时甚至拉错包 - 变量没在
composer install进程启动前注入：比如用sh -c "export COMPOSER_REPO_PACKAGIST_URL=... && composer install"，export 在子 shell 里失效 - 用了
command:而非entrypoint:：Docker Compose 的environment:确实把变量传进容器了，但若没在 entrypoint 里显式调用composer config，全局命令仍走 ~/.composer/config.json - CI runner 使用了缓存却没更新 key：比如
hashFiles('**/composer.lock')没包含 .env 或变量定义文件，导致旧缓存复用，变量实际未生效
composer install 时如何安全透传镜像变量
最简、最稳的做法是直接在 CI 脚本中拼接环境变量并执行，不依赖容器内任何预设逻辑。
- GitLab CI 示例：
script: - export COMPOSER_REPO_PACKAGIST_URL="https://mirrors.huaweicloud.com/composer/" - export COMPOSER_DISABLE_PACKAGIST=1 - composer install --no-dev --prefer-dist --optimize-autoloader --classmap-authoritative
- GitHub Actions 示例：
- name: Install dependencies run: | composer install --no-dev --prefer-dist --optimize-autoloader --classmap-authoritative env: COMPOSER_REPO_PACKAGIST_URL: https://mirrors.tuna.tsinghua.edu.cn/composer/ COMPOSER_DISABLE_PACKAGIST: 1 - 必须确保 URL 以
/结尾，否则请求路径变成https://mirrors.xxx.com/composerpackages.json→ 404 - 验证是否生效：
composer diagnose | grep "Repo packagist.org"输出应显示你设的域名，而非原始地址
全局命令（如 composer global require）怎么切镜像
这类命令完全绕过环境变量，只读 ~/.composer/config.json 里的 repo.packagist 配置。CI 中要让它生效，必须提前写入。
- 在 CI 脚本开头加：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
- 注意中间的
composer是 type 参数，不能省；URL 必须带协议、域名、路径，且以/结尾 - 执行后立即验证：
composer global show -s | grep Repository应含镜像域名 - 如果 CI runner 复用 home 目录（如 self-hosted runner），需确认
~/.composer/config.json不被上一次构建污染 - Windows 或某些 Alpine 镜像可能无写权限，先检查
ls -ld ~/.composer，必要时mkdir -p ~/.composer && chmod 755 ~/.composer
Docker Compose 场景下变量怎么“真正抵达”容器内部
environment: 字段只是把变量塞进容器的 env，但 Composer 不会自动消费它。必须让变量落地为实际配置动作。
- 别用
command: composer config -g ... ${MIRROR}：因为${MIRROR}是 Compose 解析的，到容器启动时已丢失 - 正确做法是挂载一个
entrypoint.sh，并在里面读取$COMPOSER_MIRROR并执行：#!/bin/sh if [ -n "$COMPOSER_MIRROR" ]; then composer config -g repo.packagist "https://$COMPOSER_MIRROR/" fi exec "$@"
- 然后在
docker-compose.yml中：entrypoint: ["/usr/local/bin/entrypoint.sh"] environment: - COMPOSER_MIRROR=mirrors.cloud.tencent.com
- 镜像构建时固化（适合稳定环境）：在 Dockerfile 里用
ARG MIRROR_HOST+RUN composer config -g repo.packagist ...，再通过build.args注入
真正容易被忽略的是：全局配置和项目级安装用的是两套机制，混在一起调试时，composer diagnose 显示的“Repo packagist.org”行只反映当前命令上下文的源，不是全局状态。CI 脚本里既要设环境变量，又要手动跑 config -g，缺一不可。
