多阶段构建优化前端项目生产镜像的核心是分离构建与运行：构建阶段用node镜像执行npm run build生成dist，运行阶段仅用nginx:alpine托管静态文件，不包含Node.js、源码或构建工具。

多阶段构建优化 Node.js 前端项目（如 React、Vue、Angular）的生产镜像，核心是把“构建静态资源”和“托管静态文件”彻底分开——前者用完整环境编译，后者只留最精简的 Web 服务器，不装 Node 运行时、不带源码、不跑构建命令。

明确两个阶段的分工

前端项目不需要在容器里运行 Node.js 服务，最终产物只是 HTML/CSS/JS 静态文件。所以：

• 构建阶段（builder）：用 node:18 或 node:20-slim 镜像，安装全部依赖（包括 webpack、vite、@types 等），复制 src/ 和 public/，执行 npm run build 或 yarn build，产出 dist/ 或 build/ 目录
• 运行阶段（runtime）：直接换用 nginx:alpine 或 nginx:stable-alpine，只复制构建好的 dist/ 内容，用 Nginx 提供静态服务——完全不依赖 Node.js

写一个轻量可靠的 Dockerfile

以下是一个适用于 Vite + React 项目的典型写法（Nginx 托管）：

# 构建阶段
FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
<h1>运行阶段</h1><p>FROM nginx:stable-alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

关键点：

PigX UI 前端开发

PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。

下载

立即学习“前端免费学习笔记（深入）”；

• Nginx 镜像体积仅 ~25MB，远小于任何 Node 镜像
• COPY --from=builder 只拿 dist/，src/、node_modules/、package.json 全都不进最终镜像
• 自定义 nginx.conf 可启用 gzip、缓存头、history fallback（对 Vue Router / React Router 必需）

处理常见需求细节

不是所有前端部署都一样，这些情况要单独应对：

• 需要 SSR（如 Next.js）：运行阶段仍需 Node.js，但只装 production 依赖，用 node:20-alpine + npm ci --only=production + 复制 .next/ 目录
• 需要运行时环境变量注入：不能硬编码到 JS 中，可用 Nginx 的 envsubst 或构建时通过 .env.production 替换，避免把开发密钥打进镜像
• 需要代理 API 请求：在 nginx.conf 里配 location /api { proxy_pass http://backend; }，不暴露内部服务地址
• 构建失败或体积异常大：检查是否误把 node_modules/ 或 src/ 复制进了运行阶段；用 docker history your-image 查看每层大小，确认 dist/ 是否被重复复制

验证是否真正精简

构建完成后执行几条命令快速确认效果：

• docker images：优化前可能 500MB+（含 Node + npm + dev deps），优化后应稳定在 30–60MB（纯 Nginx + 静态文件）
• docker run -it --rm your-image ls -la /usr/share/nginx/html：只看到 index.html、assets/ 文件夹，没有 src/、package.json、node_modules
• docker run -it --rm your-image sh -c 'which node || echo "Node not found"'：应输出 “Node not found”，说明没混入 Node 环境