必须在Docker构建阶段安装Composer依赖：先COPY composer.lock，再RUN composer install --no-dev等；Compose仅协调服务，不执行安装；需预装扩展、配镜像源；更新依赖应通过独立composer服务完成。
不能在容器运行时动态安装 Composer 依赖包——这是 Docker 容器化部署的核心约束。所谓“动态安装”，比如在 docker-compose up 启动后才执行 composer install，本质上违反了不可变镜像和确定性构建原则，会导致缓存失效、网络失败即退出、扩展缺失无法补救等问题。真正可行的方案，是在构建阶段完成依赖固化，再通过 Compose 实现环境协调与服务联动。
依赖必须在构建阶段完成安装
所有 PHP 依赖（vendor/）必须在 Dockerfile 的 RUN 指令中完成安装，且严格满足以下条件：
-
先复制锁文件：
COPY composer.json composer.lock ./必须出现在任何代码COPY . .之前，否则每次改代码都会破坏 Composer 缓存层 -
只用 install，不用 update：
RUN composer install --no-dev --no-interaction --optimize-autoloader，确保复现composer.lock记录的精确版本 -
提前装好扩展依赖：如
zip、mbstring、pdo_mysql等，缺一则composer install直接报错退出；例如 Debian 系需先RUN apt-get install -y libzip-dev default-libmysqlclient-dev，再docker-php-ext-install zip pdo_mysql -
配置国内镜像源：加一行
RUN composer config -g repo.packagist https://mirrors.aliyun.com/composer/，避免因网络超时中断构建
Compose 只负责协调，不负责安装
docker-compose.yml 的作用是定义服务关系、挂载策略和启动顺序，不是执行安装逻辑的场所。常见误用包括：
- 在
command:或entrypoint:中写composer install—— 这会让每次docker-compose up都重拉包，且生产环境断网即崩 - 把
vendor/挂载进容器（如volumes: - ./vendor:/var/www/html/vendor）—— 导致宿主机权限、平台差异、扩展不一致等隐性故障 - 用
depends_on强制等待数据库就绪后才跑 Composer —— 既无必要（依赖不连 DB），又掩盖了构建阶段本该解决的问题
正确做法是：Composer 安装完全在镜像构建时闭环，Compose 启动的服务直接使用已就绪的 vendor/，专注做端口映射、网络互通和健康检查。
需要临时更新依赖？用专用一次性服务
开发过程中确实存在要更新 composer.json 并重装依赖的场景，但不应污染主应用镜像。推荐在 docker-compose.yml 中定义一个独立的 composer 服务：
- 基于官方
composer镜像或带 PHP+Composer 的轻量镜像 - 挂载项目根目录（含
composer.json和composer.lock）到容器内工作路径 - 命令设为
composer install --no-dev或composer update --lock，运行完即退出 - 执行方式：
docker-compose run --rm composer，不会影响其他服务状态
这样既保持主服务镜像稳定，又能按需刷新依赖，符合职责分离原则。
验证环境一致性不能靠猜
构建成功 ≠ 运行正常。上线前务必确认容器内实际 PHP 环境与 composer.lock 要求对齐：
- 进入容器执行
php -v和php -m | grep -E 'zip|mbstring|pdo'，核对版本和扩展是否加载 - 检查
composer.lock顶部的platform字段，如"php": "8.1.10"，确保基础镜像 PHP 版本 ≥ 此值 - 若本地开发与 CI 构建结果不一致，优先对比
docker-compose build --no-cache和docker build --no-cache行为，排除缓存干扰
所有验证动作都应在构建后、部署前完成，而不是等到容器启动时报 Class not found 才排查。
