不能在容器启动时运行 composer install，因为会导致环境不一致、php扩展缺失报错、platform配置冲突、权限错误致缓存写入失败、每次启动重复安装浪费资源且破坏构建缓存。
在 Docker 里用 Composer，不是“装上就能跑”，而是必须把 composer install 放进构建阶段、用和运行时一致的 PHP 环境执行，并禁用开发依赖与脚本——否则镜像不可复现、启动慢、autoload 性能差，甚至运行时报 Class not found。
为什么不能在容器启动时运行 composer install
容器启动时执行 composer install 看似方便，但会立刻暴露环境不一致问题：
- PHP 版本或扩展（如
ext-zip、ext-openssl）缺失，直接报错Package manifest could not be loaded - 宿主机生成的
composer.lock记录的是本地平台配置（platform字段），而容器内 PHP 版本/扩展不同，会导致自动加载失败或类映射错误 - 挂载的
vendor/目录属主是 root，但应用进程以www-data或1001用户运行，写缓存失败，报Failed to write cache file - 每次启动都重装依赖，浪费时间、触发网络请求、破坏构建缓存
composer install 必须带的三个参数
生产环境构建中，这三个参数缺一不可，省略任一都会埋下性能或安全隐患：
-
--no-dev：跳过require-dev中的包（如 PHPUnit、PHPStan），避免镜像体积膨胀、减少攻击面 -
--no-scripts：不执行post-install-cmd等脚本——它们常依赖npm、node或写入权限，在构建阶段不可靠且不必要 -
--optimize-autoloader（或简写-o）：生成静态类映射，让autoload.php不再动态扫描文件，首次请求响应快、不触发慢加载超时
别碰 --ignore-platform-reqs：它会让 Composer 忽略 ext-redis 这类真实运行依赖，构建成功但运行时崩溃。
多阶段构建怎么写才不踩坑
用多阶段构建分离“装依赖”和“跑应用”，是最干净、最可复现的做法。关键点不在语法，而在路径、权限和一致性：
- 第一阶段（builder）必须用和最终运行镜像**完全一致的 PHP 基础镜像**，比如
php:8.2-cli对应php:8.2-fpm，不能混用alpine和debian变体 -
COPY composer.json composer.lock ./必须放在Dockerfile最前面，确保只要锁文件变，后续所有层缓存失效，强制重装 - builder 阶段要提前装好
unzip、git（Composer v2+ 需要）、curl，否则composer install卡在 “Could not fetch …” - 运行镜像里**不要保留
composer命令**，也不装unzip或git——精简才是目标 - 复制
vendor/时用COPY --from=builder /app/vendor /var/www/html/vendor，路径必须严格匹配，否则autoload.php找不到
本地开发时怎么快速试 composer require
开发中改依赖不能总 rebuild 镜像，但也不能直接进容器乱装——得控制作用域和生命周期：
- 用
docker-compose run --rm -v $(pwd):/app -w /app php:8.2-cli composer require foo/bar，命令执行完容器就销毁，不污染当前镜像 - 务必加
-v $(pwd):/app和-w /app，否则composer.json找不到，或生成的vendor/写到容器根目录 - 如果宿主机是 macOS/Windows，记得在
docker-compose.yml中设置user: "${UID:-1000}:${GID:-1000}"，否则生成的文件属主是 root，宿主机删不掉 - 别挂载
vendor/目录：宿主机和容器 PHP 版本稍有差异，opcache 就可能拒绝加载已编译的类，反而更慢
真正要升级依赖时，还是回到宿主机跑 composer update，提交新的 composer.lock，再重建镜像——这是唯一能保证团队协作和环境一致的方式。
