容器中 composer install 卡住或失败主因是无缓存、权限错乱、网络超时及交互阻塞；应启用 BuildKit 缓存、统一 UID、配置国内镜像、禁用交互并只用 install 保证锁文件一致。
为什么 composer install 在容器里总卡住或失败？
Docker 容器默认没有缓存，每次运行 composer install 都会重新下载全部依赖，既慢又容易因网络波动中断。更常见的是权限问题：宿主机挂载的 vendor/ 目录被 root 写入，导致后续非 root 用户（比如 PHP-FPM）无法读取。
- 容器内执行前先确认用户 UID 是否与宿主机开发用户一致，避免
vendor/权限错乱 - 不要直接挂载空目录到
vendor/—— Composer 会拒绝写入只读路径，报错Could not write to /app/vendor - 网络超时默认只有 5 分钟，国内镜像源未配置时极易触发
file could not be downloaded: failed to open stream: Connection timed out - 使用
--no-interaction --no-progress --optimize-autoloader是必须的，否则交互式提示或进度条会让构建卡死
RUN composer config -g repo.packagist composer https://packagist.phpcomposer.com && \
composer install --no-interaction --no-progress --optimize-autoloader --prefer-dist
如何让 Composer 缓存复用，不重复下载？
Docker 构建阶段的每一层都独立，~/.composer/cache 默认不会跨 RUN 指令保留。靠 COPY 本地 cache 进镜像既不可靠也不安全；正确做法是用 BUILDKIT 的 cache-mount 或显式挂载构建缓存。
- 启用 BuildKit：
DOCKER_BUILDKIT=1 docker build . - 在
Dockerfile中用# syntax=docker/dockerfile:1开头 - 用
--mount=type=cache,target=/root/.composer/cache让多次构建共享缓存 - 注意：不要把
/root/.composer/auth.json一起缓存，否则私有包凭证可能泄露
# syntax=docker/dockerfile:1
RUN --mount=type=cache,target=/root/.composer/cache \
composer install --no-interaction --optimize-autoloader
composer install 和 composer update 在容器里能混用吗？
不能。容器应视为不可变部署单元，composer update 会修改 composer.lock，破坏镜像一致性，也违背 CI/CD 中“一次构建、多环境部署”的前提。
生产镜像只允许
composer install，且必须基于已提交的composer.lock开发镜像若需动态更新依赖，应在构建后通过
docker exec进入容器手动运行composer update，但此时改完的composer.lock不会自动同步回宿主机若 CI 流程中需要生成新 lock 文件，应在宿主机完成
composer update，再提交变更，最后构建错误示范：
RUN composer update—— 导致不同时间构建的镜像依赖版本不一致正确做法：CI 脚本中先校验
composer.lock是否过期（composer validate --strict），过期则阻断构建并提醒开发者更新
PHP 版本和扩展不匹配时，composer install 报什么错？
Composer 本身不报错，但会静默跳过需特定扩展的包（如 ext-gd），直到运行时才崩。更典型的是平台配置冲突，比如 composer install 提示：
Your requirements could not be resolved to an installable set of packages.
常见原因：Dockerfile 中 PHP 版本（如
php:8.2-cli）与composer.json的"platform": {"php": "8.1"}不符扩展缺失不会阻止安装，但会触发警告：
Package x requires ext-yaml * -> the requested PHP extension yaml is missing from your system.解决方式不是忽略，而是确保基础镜像已装好扩展：
docker-php-ext-install gd mbstring zip，且注意某些扩展需额外apt-get install依赖库（如libpng-dev）判断是否真缺扩展：进容器运行
php -m | grep gd，别只信报错文字
容器里跑 Composer 不是“换个地方敲命令”，核心矛盾始终是：缓存怎么带、权限怎么对、锁文件怎么稳、扩展怎么齐。漏掉其中一环，轻则构建慢三分钟，重则上线后半夜告警。
