Composer install 必须固化在构建阶段而非启动时，核心是提前将vendor/写入镜像：需优先COPY composer.lock和composer.json、配置阿里云镜像源、使用--no-dev --optimize-autoloader参数，并通过多阶段构建精准复制vendor目录。
composer install 不该出现在容器首次启动时。
真正要解决的，是构建阶段依赖安装慢、不可复现、失败率高这几个问题。启动快不快，取决于构建是否提前把 vendor/ 固化进镜像，而不是靠启动时临时装。
为什么不能在容器启动时运行 composer install
常见错误是在 ENTRYPOINT 或 CMD 里写 composer install，这会直接导致：
- 每次
docker run都重走一遍网络请求、解压、autoloader 生成 —— 启动延迟从秒级变成几十秒甚至超时 - 镜像层不缓存
vendor/，只要 Dockerfile 任意后续行变更（比如改一行 PHP），整个依赖安装步骤就失效重跑 - 生产环境若没外网权限或没配
auth.json，composer install直接失败，报错Could not fetch packages - PHP 扩展缺失（如
ext-zip）会在启动时才暴露，但此时容器已启动失败，无法回退修复
composer install --no-dev --optimize-autoloader 必须放在构建阶段
正确做法是：把依赖安装完全固化在 Dockerfile 的 RUN 指令里，并分层优化。关键点：
-
COPY composer.json composer.lock ./要放在所有源码COPY之前 —— 否则改一行业务代码就会让依赖层失效 - 务必用
--no-dev排除开发依赖，减小镜像体积；--optimize-autoloader生成 classmap，避免运行时文件扫描 - 国内环境必须配置阿里云镜像源：
RUN composer config -g repo.packagist https://mirrors.aliyun.com/composer/ - 基础镜像别选
alpine除非你确认所有扩展（如ext-pdo,ext-redis）都已手动编译好；推荐php:8.3-cli
多阶段构建中复制 vendor/ 的坑
很多教程只写 COPY --from=builder /app/vendor /app/vendor，但漏掉两个致命细节：
Docker Image Puller
下载
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
- 最终镜像里必须确保
autoload.php存在且路径与代码中require的一致；如果 builder 阶段WORKDIR是/app，而最终镜像WORKDIR是/var/www/html，那require 'vendor/autoload.php'就会报failed to open stream - 构建完成后检查最终镜像是否残留
composer.json或composer.lock—— 它们不是运行必需，反而可能被误触发composer dump-autoload，尤其当有人手抖执行了docker exec -it app php -r "require 'vendor/autoload.php';"之类命令时
构建缓存失效的隐形原因
你以为 composer.lock 没变，Docker 就该复用缓存？不一定。以下情况会强制重建依赖层：
-
composer.lock文件编码或换行符被编辑器悄悄改过（比如 Windows 编辑器存成 CRLF） - 构建时用了不同版本的
composer（例如本地是 2.7.x，Docker 构建用的是 2.5.x），会导致 hash 计算差异 - 基础镜像升级（如
php:8.3-cli更新了 minor 版本），哪怕只差一个 patch，apt-get update结果不同也会让后续层失效
真正影响“首次启动”的，从来不是容器 runtime，而是构建是否干净、缓存是否稳定、路径是否对齐。这些点没理清，再快的网络也救不了启动延迟。
