根本原因是PHP环境缺失扩展、国内源未配置或缓存路径损坏；需在Dockerfile中安装zip/mbstring等扩展、配置国内镜像源、用composer install而非update、按正确顺序分层缓存。
为什么 composer install 在 Docker 构建时总失败？
根本原因不是 Composer 本身，而是 PHP 环境缺失扩展、国内源未配置、或缓存路径被破坏。Docker 每次构建都是干净环境，ext-zip、ext-mbstring 这类依赖没装，composer install 直接报错退出。
实操建议：
- 在
Dockerfile中先用docker-php-ext-install装齐必需扩展：比如zip、mbstring、pdo、opcache - 别跳过
apt-get update && apt-get install -y unzip—— Composer 自动安装脚本依赖unzip，缺了就卡在“Downloading…” - 加一句
RUN composer config -g repo.packagist composer https://packagist.phpcomposer.com（或阿里云镜像），否则默认走国外源，超时概率极高
composer install 和 composer update 在 Dockerfile 里该用哪个？
必须用 composer install，且确保项目根目录下已有 composer.lock。Docker 构建是部署环节，不是开发环节；composer update 会重算依赖树、忽略 lock 文件，导致镜像内版本和本地不一致，CI/CD 极易出问题。
常见错误现象：
立即学习“PHP免费学习笔记（深入）”；
- 构建成功，但运行时报
Class not found—— 因为update装了新版包，而代码只兼容旧版 - 同一份 Dockerfile 多次构建，生成的镜像 SHA 不同 ——
update时间戳和解析结果不稳定
正确写法示例（片段）：
COPY composer.json composer.lock ./ RUN composer install --no-dev --no-interaction --optimize-autoloader
如何避免每次构建都重装所有依赖？
靠分层缓存。把 composer install 放在 COPY 之后、应用代码 COPY 之前，让 Composer 缓存命中率最大化。否则只要改一行代码，整个 vendor 就得重装。
关键顺序不能错：
COPY composer.json composer.lock ./RUN composer install ...-
COPY . .（最后才拷贝源码）
注意：vendor/ 不要出现在 .dockerignore 里 —— 否则构建时压根不会用到你本地的 vendor，但也不用特意 COPY vendor/，Docker 层缓存已足够
PHP 版本不匹配导致 composer install 报错怎么办？
Composer 会检查 composer.json 中的 php 平台配置（如 "php": "^8.1"），如果基础镜像 PHP 版本低于要求，直接拒绝安装，并报类似 Your requirements could not be resolved 的模糊错误。
排查方法：
- 进容器执行
php -v，确认小版本号（比如8.1.27） - 检查
composer.json的config.platform.php是否锁死了过高版本 - 优先换基础镜像（如从
php:8.1-cli改为php:8.2-cli），而不是降级项目要求
额外提醒：有些扩展（如 ext-sodium）在 PHP 8.1+ 是内置的，旧镜像手动装反而冲突
www-data），导致 vendor/ 权限不对、autoload 文件不可读 —— 这类问题不会在构建时报错，只在容器启动后暴露。 
