多阶段构建是PHP框架容器化刚性要求，通过分离构建与运行环境，仅保留PHP运行时、应用代码及必要资源，使镜像稳定在80–120MB，显著提升启动速度、传输效率与安全性。
多阶段构建是 PHP 框架容器化最实用的瘦身手段，不是锦上添花，而是生产部署的刚性要求。它把构建环境和运行环境彻底分开，最终镜像里只留 PHP 运行时、应用代码和必要资源，不带任何编译工具、开发依赖或临时文件。
为什么 PHP 项目必须用多阶段构建
传统单阶段镜像（比如直接 FROM php:8.2-apache）会把 Composer、Node.js、Webpack、测试工具、vendor 里的 dev-dependencies 全部打包进去，体积动辄 500MB+，还暴露大量攻击面。而多阶段构建能精准控制产物交付，让最终镜像稳定在 80–120MB 左右，启动更快、传输更省、安全更强。
- 避免把
node_modules、vendor/bin、.env.*等非运行时内容打进生产镜像 - 前端资源（JS/CSS）可独立用 Node 阶段构建，再注入 PHP 运行镜像，互不干扰
- Composer 安装可单独隔离，加
--no-dev --optimize-autoloader参数，确保 vendor 干净高效 - 不同阶段可选用最适配的基础镜像：Node Alpine 做构建、PHP FPM Alpine 做运行，轻量可控
典型 Laravel 多阶段 Dockerfile 结构
一个标准的三阶段构建流程，覆盖前端编译、依赖安装、运行整合：
-
前端构建阶段（frontend）：基于
node:alpine，仅拷贝package.json和资源目录，执行npm run production，产出压缩后的public/js和public/css -
Composer 安装阶段（composer）：基于
composer:2或php:8.2-cli-alpine，跳过平台检查与脚本执行，生成优化过的vendor/ -
运行整合阶段（laravel）：基于
php:8.2-fpm-alpine，COPY 上两阶段产物 + 应用源码，配置 Nginx / PHP-FPM，设置非 root 用户权限
关键点：COPY --from=frontend 和 COPY --from=composer 必须精确到子路径，不能 COPY 整个构建目录，否则容易混入隐藏文件或缓存垃圾。
立即学习“PHP免费学习笔记（深入）”；
配套必须做的几件事
多阶段构建效果好不好，一半靠 Dockerfile 写法，一半靠周边配合：
-
.dockerignore 要写实：至少排除
.git、node_modules、vendor、storage/、bootstrap/cache/、.env.*、yarn-error.log—— 这些不进镜像，也不参与缓存计算 -
PHP 配置要精简：运行镜像中禁用
display_errors、开启opcache.enable=1、设memory_limit=256M，这些都应在php.ini或通过docker-php-ext-enable注入 -
基础镜像选 Alpine：PHP 官方提供
php:8.2-fpm-alpine，体积比 Debian 版小 60% 以上；注意 Alpine 的 musl libc 兼容性，扩展需用apk add安装而非 pecl -
构建时加缓存参数：CI 中用
docker build --cache-from或 GitHub Actions 的actions/cache缓存~/.composer/cache和node_modules，大幅缩短重复构建时间
验证与调试技巧
构建完别急着上线，先确认镜像是否真的“干净”：
- 运行
docker run -it --rm your-laravel-image sh，进容器后执行ls -la和php -m，检查有没有多余扩展或可疑目录 - 用
docker history your-laravel-image查看各层大小，确认 vendor 和 public 资源层是否独立、构建工具层是否被丢弃 - 对比单阶段 vs 多阶段镜像的
docker images输出，体积差应达 6–7 倍，否则说明某阶段 COPY 过宽或 .dockerignore 没生效 - 本地测试时，可用
docker build --target frontend -t laravel-frontend .单独构建前端阶段，快速验证构建逻辑
