核心是所有Composer配置必须显式注入容器：在Dockerfile中用RUN composer config -g设置镜像源，Alpine需先装ca-certificates；确保composer.lock先于composer.json复制以利用缓存；多阶段构建中两阶段PHP镜像版本与发行版须完全一致；权限问题通过-u指定UID/GID或chown修复；platform配置须与容器真实PHP版本严格匹配。
在 Docker 容器里配 Composer，核心就一条：别指望宿主机的配置能自动生效，所有设置必须显式注入容器内部。 否则你会遇到镜像构建卡住、composer install 报错、缓存写不进、甚至 vendor 目录权限拒绝——这些问题全是因为配置没落进容器上下文里。
怎么让 composer config -g 生效
宿主机上运行 composer config -g repo.packagist https://mirrors.aliyun.com/composer/ 对容器完全无效。Docker 构建时用的是全新环境，~/.composer/config.json 根本不存在。
- 必须在
Dockerfile中用RUN composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/显式设置 - 如果基础镜像是 Alpine，得先装证书：
RUN apk add --no-cache ca-certificates，否则 HTTPS 镜像源会报SSL certificate problem - 避免用
COMPOSER_REPO_PACKAGIST环境变量替代config -g—— 它只影响当前命令，不持久化，后续composer require仍可能回退到默认源
为什么 RUN composer install 总卡在 “Resolving packages…”
这不是 Composer 慢，是它在等 packagist.org 响应，而国内直连基本超时。即使你设了镜像源，也可能被其他配置覆盖。
- 确认
composer.lock和composer.json是最先COPY进镜像的，且顺序是lock在前、json在后；否则 Composer 会退化成update行为，触发完整解析 - 加
--no-interaction -vvv查看真实请求地址：RUN composer install --no-interaction -vvv 2>&1 | grep "Downloading"，验证是否真走阿里云源 - 别在
RUN前挂载.dockerignore忽略了composer.lock—— 这会导致构建时找不到 lock 文件，强制升级依赖
容器内执行 composer require 报 Permission denied
错误不是 Composer 本身，是文件系统权限错位：Mac/Windows 宿主机挂载的目录默认属主是 root:root（uid=0），但 PHP 容器常用用户是 www-data（uid=33）或 1001，根本没法写 vendor/ 或 composer.json。
- 启动容器时用
-u $(id -u):$(id -g)显式指定 UID/GID，例如：docker run -u $(id -u):$(id -g) -v $(pwd):/app php:8.2-cli composer require monolog/monolog - 如果已生成了 root 属主的
vendor/，进容器后先修复：chown -R 1001:1001 vendor/（按实际容器用户 UID 调整） - 开发中想热更新依赖，更稳妥的做法是挂载宿主机
vendor/并提前chown，而不是依赖容器内动态安装
多阶段构建中 vendor 复制后 autoload 失败
常见于 builder 阶段用 php:8.2-cli，final 阶段却用 php:8.2-apache —— 两者扩展集不同，导致 vendor/autoload.php 生成时依赖的扩展（如 ext-zip）在运行时缺失，类加载直接报错。
- 两个阶段必须用完全一致的 PHP 基础镜像标签，包括版本、SAPI 类型、发行版（alpine/debian）
- builder 阶段加
--no-scripts，避免执行需要 node/npm 的 post-install-cmd，这些脚本在 final 阶段根本不可用 - final 阶段不要重复
COPY --from=builder /app/vendor /app/vendor后再跑composer dump-autoload—— 这会破坏 builder 阶段已优化的静态映射，应该在 builder 阶段就跑composer dump-autoload --optimize
最易被忽略的一点：Composer 的 platform 配置必须和容器内真实环境对齐。比如 composer.json 里写了 "config": {"platform": {"php": "8.2.0"}}，但 Dockerfile 里用的是 php:8.1-cli，composer install 就会失败。别依赖 --ignore-platform-reqs 掩盖问题，它只是把崩溃推迟到运行时。
