多阶段构建必须用于前端项目，因其能将构建与运行环境彻底分离：单阶段会把node_modules、源码、构建工具全打入镜像，导致体积超1gb且存在安全风险；多阶段则仅在builder阶段完成npm build，运行阶段只保留nginx和dist静态文件，镜像约50mb，启动快、攻击面小、符合生产规范。
直接用多阶段构建，把前端构建和 Nginx 运行彻底分开，既安全又轻量。
为什么必须用多阶段
单阶段打包会把 node_modules、源码、构建工具全塞进最终镜像，体积动辄 1GB+，还带安全隐患。多阶段让构建只发生在 builder 阶段，运行时只留 Nginx 和压缩后的静态文件，镜像通常压到 50MB 左右，启动快、攻击面小、符合生产规范。
标准 Dockerfile 写法
以下是最常用且稳定的写法，适配 React/Vue 等主流框架：
- 构建阶段：基于 node:16-alpine 或 node:18-alpine，安装依赖并执行 npm run build
- 运行阶段：切换为 nginx:alpine，用 COPY --from=builder 把 dist 目录复制过去
- 覆盖配置：自定义 nginx.conf 放在项目根目录，COPY 到 /etc/nginx/conf.d/default.conf（不是 nginx.conf 主配置）
- 暴露端口：EXPOSE 80 是声明，实际映射靠 docker run -p 完成
关键细节不能漏
很多问题出在细节上：
- 确保 .dockerignore 文件包含 node_modules、src、.git、package-lock.json 等，避免误传大文件
- COPY 构建产物时路径要对：dist/ 或 build/ 取决于你实际输出目录，别写错成 ./dist/ 或 dist
- 如果要用 history.pushState（如 Vue Router 或 React Router），nginx.conf 必须加 try_files 指令，否则刷新 404
- 不要在运行阶段 RUN rm /usr/share/nginx/html/* —— COPY 会自动覆盖，多余操作反而可能出错
验证与运行
构建后建议快速验证两件事：
- docker build -t my-fe-app . 成功后，docker images 看镜像大小是否合理（
- docker run -d -p 8080:80 --name test-app my-fe-app 启动，curl http://localhost:8080 看返回 HTML 内容
- 进容器检查文件：docker exec -it test-app ls /usr/share/nginx/html/，确认 index.html 和 js/css 文件都在
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
