在 Docker 容器启动时执行 composer install 是反模式，正确做法是将依赖安装固化在构建阶段，分层优化：先装系统依赖和 PHP 扩展，再复制 composer.lock 和 composer.json，接着安装 Composer 并运行 composer install --no-dev --optimize-autoloader，最后复制源码。
在 Docker 容器启动时执行 composer install 是反模式，会导致镜像不可复现、启动变慢、缓存失效，且违反容器“一次构建、多次运行”原则。正确做法是：把依赖安装固化在构建阶段。
为什么不能在 docker run 时才装依赖
常见错误是在 ENTRYPOINT 或 CMD 中调用 composer install，这会带来几个实际问题：
- 每次启动都重装，浪费时间（尤其网络不稳定时失败率高）
-
vendor/不进镜像层，无法利用 Docker 构建缓存，Dockerfile中任何后续变更都会导致 composer 步骤重新执行 - 生产环境没权限连外网（或没配置
COMPOSER_HOME/auth.json），直接报错Could not fetch packages - PHP 运行时可能缺扩展（如
ext-zip），composer install在启动时才发现，已来不及修复
composer install 必须放在构建阶段，且要分层优化
关键不是“能不能做”，而是“怎么分层才能快又稳”。推荐写法如下（以 PHP 8.2 + Apache 为例）：
FROM php:8.2-apache1. 安装系统依赖和 PHP 扩展（提前做，利于缓存）
RUN apt-get update && apt-get install -y \ git zip unzip \ && docker-php-ext-install zip
2. 复制 composer.lock 和 composer.json（单独一层，利用缓存）
COPY composer.lock composer.json /var/www/html/
3. 安装 Composer（可选，推荐用官方 installer）
RUN curl -sS https://www.php.cn/link/e910517884e11c8a741c3b1da823f47e | php -- --install-dir=/usr/local/bin --filename=composer
4. 安装 PHP 依赖（--no-dev --optimize-autoloader 生产必需）
RUN cd /var/www/html && composer install --no-dev --optimize-autoloader --no-interaction
5. 复制源码（最后复制，避免因代码变更触发前面所有层重建）
COPY . /var/www/html/
6. 权限与启动
RUN chown -R www-data:www-data /var/www/html EXPOSE 80 CMD ["apache2-foreground"]
注意点：
-
composer.lock必须COPY在composer install前，否则无法命中缓存 - 不要用
ADD替代COPY，ADD会自动解压 tar 包，行为不可控 - 如果项目用 private repo，需在构建时注入
auth.json（用BUILDKIT的--secret或挂载临时文件）
如何安全处理私有仓库认证（auth.json）
把 token 写进镜像或 Dockerfile 是严重安全隐患。正确方式是构建时传入，运行时不落地：
# 构建命令（需启用 BuildKit） DOCKER_BUILDKIT=1 docker build \ --secret id=composer-auth,src=./auth.json \ -t myapp .Dockerfile 中使用
RUN --mount=type=secret,id=composer-auth,dst=/tmp/auth.json \ cp /tmp/auth.json /root/.composer/auth.json && \ cd /var/www/html && composer install --no-dev --optimize-autoloader
这样 auth.json 不会出现在任何镜像层中，也无需在 CI 环境硬编码凭证。
多阶段构建进一步精简镜像体积
若项目含前端构建（如 Laravel Mix）、测试工具等非运行时依赖，用多阶段可减小最终镜像：
FROM php:8.2-cli AS builder RUN apt-get update && apt-get install -y unzip git RUN curl -sS https://www.php.cn/link/e910517884e11c8a741c3b1da823f47e | php -- --install-dir=/usr/local/bin --filename=composer COPY composer.lock composer.json /app/ WORKDIR /app RUN composer install --no-dev --optimize-autoloaderFROM php:8.2-apache COPY --from=builder /app/vendor /var/www/html/vendor COPY . /var/www/html
... 后续同上
最终镜像里只有 vendor/ 和源码，不含 composer 二进制、git、unzip 等构建工具。
最常被忽略的一点：本地开发时很多人用 bind mount 覆盖整个 /var/www/html，结果容器内 vendor/ 被宿主机空目录覆盖——这时即使构建时装好了，运行时也等于没装。务必确认 volume 挂载路径避开 vendor/，或用 docker compose 的 overrides 分离开发/生产配置。
