最核心方案是多阶段构建+严格分层缓存+非root运行；因生产镜像缺git/zip等依赖、宿主机环境不一致易致Class not found或权限错误，且违反最小权限原则。
在 Docker 中用 Composer 部署 PHP 应用，最核心的判断是：别让 composer install 跑在最终运行镜像里，也别在宿主机上装 Composer 来生成 vendor。真正安全、可复现、轻量的方案，只有一条路——多阶段构建 + 严格分层缓存 + 非 root 运行。
为什么不能直接在生产镜像里运行 composer install
常见错误现象：docker build 卡在 composer install 步骤、镜像体积暴涨 200MB+、容器启动时报 Class not found 或权限拒绝（vendor 目录属主是 root）、CI 构建因网络波动失败。
- PHP 运行时镜像（如
php:8.2-fpm-alpine）默认不带git、zip、unzip，composer install会直接报错退出 - 把 Composer 和它的临时文件打进最终镜像，既增大攻击面，又违反最小权限原则
- 宿主机执行
composer install再挂载vendor，会导致 macOS/Windows 上的文件权限/行尾符问题，且docker-compose up后修改代码可能触发 autoload 重生成失败
多阶段构建中 composer install 的正确写法
关键不是“怎么装”，而是“在哪装、装完怎么交出去”。第一阶段必须独立、干净、可缓存。
- 使用专用 builder 镜像，例如
FROM composer:2 AS composer或FROM php:8.3-cli AS builder（后者更可控，能统一扩展） - 先
COPY composer.json composer.lock ./，再RUN composer install --no-dev --optimize-autoloader --no-progress --no-interaction—— 顺序颠倒会导致每次改代码都重装依赖 - 如果项目含私有包，用
--secret id=composer_auth,src=$HOME/.composer/auth.json挂载认证文件，避免硬编码或泄露到镜像层 - 不要在 builder 阶段
COPY . .，除非你真需要运行 post-install-cmd 脚本；否则只复制依赖文件即可
运行阶段如何安全移交 vendor 目录
移交不是简单 COPY --from=builder 就完事。权限、用户、路径三者错一个，FPM 就起不来。
- 目标镜像（如
php:8.3-fpm-alpine）需提前创建非 root 用户：RUN adduser -D -u 1001 -s /bin/sh app -
COPY --from=builder --chown=app:app /app/vendor ./vendor—— 必须带--chown，否则vendor属主仍是 root - 确保工作目录（
WORKDIR /var/www/html）和vendor在同一挂载点下，否则 PSR-4 自动加载可能找不到类 - 若用
docker-compose.yml挂载源码卷，vendor必须**不被覆盖**：volumes列表里不要包含./vendor:/var/www/html/vendor
开发环境用 docker-compose run 执行 composer 命令的坑
这是本地调试最常用的方式，但容易忽略环境一致性。
- 命令必须显式指定用户：
docker-compose run --rm --user ${UID:-1000}:${GID:-1000} php composer install，否则生成的vendor文件属主是 root，宿主机无法修改 - 务必挂载
~/.composer/cache到容器内：volumes: ["$HOME/.composer/cache:/root/.composer/cache"]，否则每次都是冷下载 - 加
PHP_MEMORY_LIMIT=2G环境变量，防止大项目 autoload 生成时 OOM（尤其 Laravel + lots of packages） - 别用
docker-compose exec进容器再手动敲composer install—— 容器内没设好COMPOSER_HOME或权限，容易写坏 cache 或生成错误的autoload_classmap.php
最易被忽略的点是：多阶段构建中，builder 阶段安装的 PHP 扩展（如 redis、gd）必须和运行阶段完全一致；否则 vendor 里某些包的条件加载逻辑会失效，运行时报 class not found 却查不到原因。
