项目背景
在开发 Three.js 微前端项目时，面临以下容器化挑战：
Monorepo 架构：pnpm workspace 管理多个微应用和共享包
构建时间长：每次构建需要安装依赖 + 编译，耗时 5-10 分钟
镜像体积大：包含 node_modules 的镜像超过 500MB
缓存失效频繁：代码修改导致整个镜像重新构建
配置管理复杂：多环境配置需要灵活切换
本文分享一套多阶段构建 + 智能脚本的容器化解决方案，将构建时间缩短 70%，镜像体积减少 90%。
技术方案架构
核心设计理念
多阶段构建：依赖安装、源码编译、生产运行三阶段分离
层级缓存优化：最小化缓存失效范围，提升重复构建速度
自动化脚本：一键构建、验证、清理，支持多种构建模式
配置外部化：配置文件与代码分离，支持运行时动态修改
技术栈
Docker Multi-stage Build：多阶段构建
PNPM Workspace：Monorepo 依赖管理
Nginx Alpine：轻量级 Web 服务器
Bash Script：自动化构建脚本
核心实现
1. 多阶段 Dockerfile 设计
传统单阶段构建的问题
# ❌ 传统方案：所有内容打包到一个镜像
FROM node:lts-alpine
WORKDIR /app
COPY . .
RUN pnpm install && pnpm build
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
问题：
✗ 镜像包含 node_modules（500MB+）
✗ 任何代码修改都重新安装依赖
✗ 构建产物和源码混在一起
优化后的多阶段构建
# ============================================
# 阶段 1: 依赖安装（利用 Docker 缓存）
# ============================================
FROM node:lts-alpine AS deps
ARG MODULE=main-app
WORKDIR /app
# 📌 策略：只复制依赖配置文件，触发缓存
COPY pnpm-workspace.yaml package.json pnpm-lock.yaml ./
COPY packages/${MODULE}/package.json ./packages/${MODULE}/
COPY packages/shared/package.json ./packages/shared/
# 安装依赖（此层会被缓存，除非依赖文件变化）
RUN npm install -g pnpm@7.33.6 && \
pnpm install --filter @fiber-study/${MODULE} --filter @fiber-study/shared --frozen-lockfile && \
pnpm store prune
# ============================================
# 阶段 2: 源码构建
# ============================================
FROM node:lts-alpine AS build
ARG MODULE=main-app
WORKDIR /app
# 📌 策略：只复制 node_modules，避免旧构建产物污染
COPY --from=deps /app/node_modules ./node_modules
COPY --from=deps /app/packages/shared/node_modules ./packages/shared/node_modules
COPY --from=deps /app/packages/${MODULE}/node_modules ./packages/${MODULE}/node_modules
# 复制源码（共享模块 + 目标模块）
COPY packages/shared ./packages/shared
COPY packages/${MODULE} ./packages/${MODULE}
# 构建（清理旧产物，确保干净构建）
RUN npm install -g pnpm@7.33.6 && \
echo "🔨 Building ${MODULE}..." && \
rm -rf packages/${MODULE}/dist && \
pnpm --filter @fiber-study/${MODULE} build && \
rm -rf node_modules packages/*/node_modules
# ============================================
# 阶段 3: 生产运行（最小镜像）
# ============================================
FROM nginx:alpine
ARG MODULE=main-app
# 📌 策略：只复制构建产物，不包含任何源码和依赖
COPY --from=build /app/packages/${MODULE}/dist /usr/share/nginx/html
COPY nginx-common.conf /etc/nginx/conf.d/default.conf
# 健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD wget --quiet --tries=1 --spider http://localhost/ || exit 1
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
优势对比
2. 智能构建脚本设计
功能矩阵
#!/bin/bash
# build.sh - 多模式构建脚本
# ✅ 支持的功能：
# - 普通构建：快速构建，利用缓存
# - 无缓存构建：强制重新构建所有层（配置修改后）
# - 深度清理：清理本地产物 + Docker 缓存
# - 镜像验证：构建后自动验证内容
# - 标签管理：自定义镜像版本
# - 镜像推送：构建后推送到仓库
核心功能实现
1. 深度清理模式
# 解决问题：配置文件修改后，Docker 缓存导致不生效
if [ "$DEEP_CLEAN" = true ]; then
echo "📦 执行深度清理..."
# 清理本地构建产物
rm -rf "packages/$MODULE/dist"
# 清理 Vite 缓存（Vite 会缓存编译结果）
rm -rf "packages/$MODULE/node_modules/.vite"
# 询问是否清理 Docker 构建缓存
read -p "是否清理所有 Docker 构建缓存？(y/N): " -n 1 -r
if [[ $REPLY =~ ^[Yy]$ ]]; then
docker builder prune -af
fi
fi
使用场景：
修改了 config.js、vite.config.ts 等配置文件
更新了环境变量或构建参数
遇到"代码修改了但页面没变"的问题
2. 无缓存构建
# 解决问题：Docker 层缓存可能导致配置不更新
if [ "$NO_CACHE" = true ]; then
BUILD_ARGS="$BUILD_ARGS --no-cache"
echo "⚠️ 使用 --no-cache（所有层将重新构建）"
fi
使用场景：
Nginx 配置修改后
依赖版本更新后
需要确保完全干净的构建
3. 镜像验证
# 解决问题：构建成功但内容不对
if [ "$VERIFY" = true ]; then
echo "🔍 验证镜像内容..."
# 启动临时容器
docker run -d --name verify-$MODULE -p 8888:80 $IMAGE_NAME
# 检查健康状态
sleep 3
if curl -f http://localhost:8888 > /dev/null 2>&1; then
echo "✅ 镜像验证通过"
else
echo "❌ 镜像验证失败"
fi
# 清理临时容器
docker rm -f verify-$MODULE
fi
使用示例
# 1. 普通构建（开发日常）
./build.sh main-app
# 2. 配置修改后（推荐）
./build.sh -n main-app
# 3. 遇到缓存问题（彻底清理）
./build.sh -C -v main-app
# 4. 生产发布
./build.sh -t v2.0.1 -p main-app
# 5. 多模块构建
./build.sh -t latest main-app
./build.sh -t latest player-control
3. Docker Compose 编排
微前端服务编排
version: '3.8'
services:
# 主应用（底座）
main-app:
build:
context: .
dockerfile: dockerfile
args:
MODULE: main-app
image: main-app:v1
ports:
- "5173:80"
volumes:
# 📌 配置外部化：运行时可修改
- ./packages/main-app/public/config.js:/usr/share/nginx/html/config.js:ro
# 📌 日志挂载：便于调试
- ./logs/main-app:/var/log/nginx
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
interval: 30s
timeout: 3s
retries: 3
networks:
- fiber-study
# 微前端模块
player-control:
build:
args:
MODULE: player-control
image: player-control:v1
ports:
- "3001:80"
volumes:
- ./packages/player-control/public/micro-app-config.js:/usr/share/nginx/html/config.js:ro
- ./logs/player-control:/var/log/nginx
networks:
- fiber-study
networks:
fiber-study:
driver: bridge
设计亮点
配置与代码分离
配置文件通过 volume 挂载
修改配置无需重新构建镜像
支持多环境配置切换
健康检查机制
自动检测服务可用性
异常时自动重启
避免流量打到故障实例
日志外部化
日志持久化到宿主机
便于问题排查和监控
不增加镜像体积
技术亮点深度剖析
1. 层级缓存优化策略
Docker 构建层级设计
# 第 1 层：基础镜像（几乎不变）
FROM node:lts-alpine AS deps
# 第 2 层：依赖配置文件（偶尔变化）
COPY pnpm-workspace.yaml package.json pnpm-lock.yaml ./
COPY packages/${MODULE}/package.json ./packages/${MODULE}/
# 第 3 层：依赖安装（依赖文件变化时才重建）
RUN pnpm install --frozen-lockfile
# 第 4 层：源码（频繁变化，但不影响前面的缓存）
COPY packages/shared ./packages/shared
COPY packages/${MODULE} ./packages/${MODULE}
# 第 5 层：构建（每次都执行，但前面的缓存加速了依赖安装）
RUN pnpm build
缓存命中率
2. Monorepo 依赖管理
问题：共享模块的依赖安装
# ❌ 错误做法：只安装目标模块
pnpm install --filter @fiber-study/player-control
# 问题：shared 模块依赖未安装，编译失败
解决方案：同时安装共享模块
# ✅ 正确做法：同时安装共享模块和目标模块
RUN pnpm install \
--filter @fiber-study/${MODULE} \
--filter @fiber-study/shared \
--frozen-lockfile
3. 构建产物污染预防
问题场景
# 场景：本地开发后直接构建 Docker 镜像
# 问题：本地 dist/ 目录被复制到镜像中，导致混用新旧代码
解决方案
# 方案 1：Dockerfile 中清理（推荐）
RUN rm -rf packages/${MODULE}/dist && \
pnpm build
# 方案 2：.dockerignore 排除
# .dockerignore
packages/*/dist
packages/*/node_modules
# 方案 3：构建脚本深度清理
./build.sh -C main-app # 自动清理本地产物
性能优化数据
构建时间对比
场景 1：首次构建（冷启动）
场景 2：代码修改后重新构建
场景 3：依赖未变化（日常开发）
单阶段：每次 7 分钟
多阶段：每次 2.5 分钟
节省时间：64%
镜像体积对比
实际应用场景
场景 1：CI/CD 流水线
# GitHub Actions / GitLab CI
name: Build and Deploy
on:
push:
branches: [main, develop]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
# 利用 Docker 缓存
- name: Build with cache
run: ./build.sh -t ${{ github.sha }} main-app
# 推送到镜像仓库
- name: Push to registry
run: docker push main-app:${{ github.sha }}
优势：
✅ 增量构建，节省 CI 时间和成本
✅ 每个 commit 都有对应镜像，便于回滚
✅ 多阶段构建减少网络传输时间
场景 2：多环境部署
# 开发环境
./build.sh -t dev main-app
docker-compose -f docker-compose.dev.yml up -d
# 测试环境
./build.sh -t staging main-app
docker-compose -f docker-compose.staging.yml up -d
# 生产环境
./build.sh -t v1.0.0 -p main-app
docker-compose -f docker-compose.prod.yml up -d
优势：
✅ 同一套代码，不同配置文件
✅ 配置外部化，无需重新构建
✅ 版本化管理，便于追溯
场景 3：本地开发调试
# 1. 快速构建测试
./build.sh main-app
# 2. 启动容器
docker-compose up -d main-app
# 3. 查看日志
tail -f logs/main-app/access.log
# 4. 修改配置（无需重启）
vim packages/main-app/public/config.js
# 5. 验证配置生效
curl http://localhost:5173/config.js
优势：
✅ 快速验证容器化部署
✅ 配置修改实时生效
✅ 日志实时查看
问题排查与解决
常见问题 1：配置修改后不生效
现象：
# 修改了 config.js，但页面显示的还是旧配置
原因：
Docker 层缓存了旧的配置文件
Vite 编译缓存未清理
解决方案：
# 方案 1：深度清理构建
./build.sh -C main-app
# 方案 2：无缓存构建
./build.sh -n main-app
# 方案 3：清理 Docker 构建缓存
docker builder prune -af
常见问题 2：构建失败但本地正常
现象：
# 本地 pnpm dev 正常，Docker 构建报错
Error: Cannot find module '@fiber-study/shared'
原因：
Monorepo 依赖未正确安装
workspace 配置未复制到容器
解决方案：
# 确保复制 workspace 配置
COPY pnpm-workspace.yaml ./
# 同时安装共享模块
RUN pnpm install \
--filter @fiber-study/${MODULE} \
--filter @fiber-study/shared
常见问题 3：镜像体积异常大
现象：
# 镜像体积 600MB+，预期应该 50MB 左右
原因：
单阶段构建包含了 node_modules
没有使用 alpine 基础镜像
解决方案：
# 使用多阶段构建 + alpine 镜像
FROM nginx:alpine # 而不是 nginx:latest
# 只复制构建产物
COPY --from=build /app/packages/${MODULE}/dist /usr/share/nginx/html
技术扩展思考
1. 构建加速
Docker BuildKit 加速
# 启用 BuildKit（并行构建层）
DOCKER_BUILDKIT=1 docker build .
# 性能提升：30%+
远程缓存
# 使用 Docker Registry 作为缓存源
docker buildx build \
--cache-from=type=registry,ref=myregistry/myapp:cache \
--cache-to=type=registry,ref=myregistry/myapp:cache,mode=max \
.
2. 安全加固
非 root 用户运行
# 创建非 root 用户
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser
# 提升安全性
多阶段构建隔离敏感信息
# 构建阶段使用 Secret
RUN --mount=type=secret,id=npmrc \
npm config set //registry.npmjs.org/:_authToken=$(cat /run/secrets/npmrc)
# 生产镜像不包含 Secret
3. 镜像优化
压缩静态资源
# 使用 Brotli/Gzip 压缩
RUN apk add --no-cache brotli && \
find /usr/share/nginx/html -type f \( -name '*.js' -o -name '*.css' \) \
-exec brotli {} \; \
-exec gzip -k {} \;
资源 CDN 加速
# Nginx 配置：静态资源设置长缓存
location ~* \.(js|css|png|jpg|jpeg|gif|ico|woff|woff2)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
最佳实践总结
构建策略
日常开发：使用默认构建，利用缓存
./build.sh main-app配置修改：使用无缓存构建
./build.sh -n main-app遇到问题：使用深度清理
./build.sh -C -v main-app生产发布：使用版本标签
./build.sh -t v1.0.0 -p main-app
镜像管理
版本化命名：使用语义化版本
开发：
main-app:dev测试：
main-app:staging生产：
main-app:v1.0.0
定期清理：避免磁盘占满
docker system prune -af --volumes健康检查：确保服务可用性
healthcheck: test: ["CMD", "wget", "--spider", "http://localhost/"] interval: 30s
总结
本方案通过多阶段构建 + 智能脚本 + 配置外部化，实现了高效、灵活的微前端容器化部署：
核心价值
性能提升
构建时间减少 64%（日常开发场景）
镜像体积减少 93.6%（700MB → 45MB）
缓存命中率 75%+
开发体验
✅ 一键构建多种模式（普通/无缓存/深度清理）
✅ 配置热更新，无需重新构建
✅ 详细的构建日志和验证机制
生产就绪
✅ 健康检查和自动重启
✅ 日志持久化和监控
✅ 多环境配置管理
技术亮点
Docker 层级缓存优化：精细化的层级设计
Monorepo 依赖管理：正确处理共享模块
自动化脚本：覆盖全生命周期的构建工具
配置与代码分离：运行时配置修改
这套方案已在生产环境稳定运行，支撑多个微前端应用的容器化部署，显著提升了团队的开发和部署效率。
相关技术栈
Docker Multi-stage Build：多阶段构建
PNPM Workspace：Monorepo 管理
Vite：前端构建工具
Nginx：Web 服务器
Docker Compose：容器编排