应将 composer 国内镜像源固化到 docker 构建阶段，如在 dockerfile 中用 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，避免运行时临时配置失效或影响宿主机，同时注意镜像源有效性及 zip 扩展依赖。
在 Docker Compose 环境中直接用 composer install 却卡在 GitHub 或 Packagist 下载，不是 Composer 本身坏了，而是它默认走境外源，在容器里没配镜像时，根本连不上。
docker-compose.yml 里不能直接写 composer config
很多人想当然地在 docker-compose.yml 的 command 或 entrypoint 里加 composer config -g repo.packagist composer https://packagist.phpcomposer.com，这行不通——因为 composer config -g 写的是宿主机用户家目录下的 ~/.composer/config.json，而容器里压根没这个路径，也没权限写宿主机文件。
- 容器内执行的
composer config -g操作，实际影响的是容器内部的/root/.composer/config.json（如果以 root 运行）或/home/www-data/.composer/config.json（如果以 www-data 运行），但这个配置只在当前容器生命周期有效，下次重建就丢 - 更麻烦的是：很多 PHP 镜像（比如
php:8.2-cli）默认不预装 Composer，你得自己curl -sS https://getcomposer.org/installer | php，再mv composer.phar /usr/local/bin/composer，否则连composer命令都没有 - 正确做法是把镜像配置固化进构建阶段，而不是运行时临时改
Dockerfile 中提前设置国内镜像源
最稳妥的方式，是在构建 PHP 容器镜像时，就把 Composer 镜像源写死进全局配置。这样每次容器启动都自带加速能力，不依赖外部环境。
示例 Dockerfile 片段：
FROM php:8.2-cli
RUN apt-get update && apt-get install -y curl git unzip \
&& rm -rf /var/lib/apt/lists/*
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
RUN composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
注意三点：
- 用
https://mirrors.aliyun.com/composer/替代已停用的https://packagist.phpcomposer.com（后者自 2022 年起已不可用） -
composer config -g必须在composer命令可用之后执行，顺序不能颠倒 - 如果镜像里用了非 root 用户（比如
www-data），要显式切换用户再配：su www-data -c "composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/"
docker-compose.yml 启动时挂载自定义 config.json
不想 rebuild 镜像？可以用 volume 把本地已配好的 config.json 挂进去，覆盖容器内默认位置。
先在项目根目录建 composer-config/config.json，内容如下：
{
"repositories": {
"packagist": {
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
}
}
}
然后在 docker-compose.yml 里挂载：
services:
app:
image: my-php-app
volumes:
- ./composer-config/config.json:/root/.composer/config.json:ro
关键点：
- 路径必须严格匹配：root 用户对应
/root/.composer/config.json，非 root 用户需改成对应家目录，比如/home/www-data/.composer/config.json - 加
:ro表示只读，避免容器意外改写宿主机配置 - 该方式适合调试或临时切换源，不适合 CI/CD 流水线——因为 config.json 会进 Git，敏感信息（如私有 repo token）不能明文放这里
build 时用 ARG 动态注入镜像源
团队协作时，可能需要不同环境用不同源（比如 dev 用阿里云，prod 用公司内网镜像）。这时用 ARG + 构建参数最灵活。
Dockerfile 中：
ARG COMPOSER_MIRROR=https://mirrors.aliyun.com/composer/
RUN composer config -g repo.packagist composer ${COMPOSER_MIRROR}
构建命令：
docker build --build-arg COMPOSER_MIRROR=https://pkg.phpcomposer.com/ -t myapp .
注意：
-
ARG只在构建阶段生效，无法在容器运行时修改；若要 runtime 切换，仍需靠挂载 config.json 或 entrypoint 脚本 - 别漏掉
docker-compose.yml里的build:配置，否则docker-compose up不会触发 build 参数传递 - 阿里云镜像目前最稳，腾讯云、华为云镜像偶尔有同步延迟，生产环境建议固定用阿里云地址
真正容易被忽略的，是镜像源地址的有效性——packagist.phpcomposer.com 已失效三年多，但大量旧教程还在引用；另外，PHP 镜像里若没装 unzip，composer install 会直接报错 “zip extension not loaded”，这个和镜像源无关，但常被误判为网络问题。
