Vue3 前端项目 Docker 容器化部署教程
本教程将带你从零开始，使用 Docker + Nginx 将一个 Vue3 前端项目打包并运行在容器中。我们会用到三个关键文件：
.dockerignore—— 控制哪些文件不被复制进镜像Dockerfile—— 定义构建和运行镜像的步骤deploy/nginx.conf—— 配置 Nginx 作为静态资源服务器
最终效果：
- 前端代码会在容器中构建
- 构建产物交由 Nginx 提供服务
- 支持 Vue Router history 模式
- 可选反向代理后端 API
- 启用 gzip 压缩和缓存优化
📂 项目结构示例
vue3-docker-app/
├── deploy/ # 部署相关配置文件
│ └── nginx.conf # Nginx 配置文件（生产环境）
...
├── .dockerignore # Docker 构建忽略文件
├── Dockerfile # Docker 镜像构建文件
├── package.json # 项目依赖和脚本
...
🔑 说明
deploy/：专门存放部署相关的配置文件（如nginx.conf、CI/CD 脚本）.dockerignore：避免无关文件进入镜像，减小体积Dockerfile：定义构建和运行镜像的步骤package.json：依赖和脚本管理
1️⃣ .dockerignore
.dockerignore 文件的作用类似于 .gitignore，它告诉 Docker 在构建镜像时不要复制哪些文件，避免无用文件进入镜像，减小体积并加快构建速度。
完整文件如下：
# 依赖目录
node_modules
npm-debug.log
.npm# 构建产物
dist
.output# 版本控制
.git
.gitignore# IDE 配置
.vscode
.idea
*.swp
*.swo
.DS_Store# 环境文件
#.env*.local
#.env.development
#.env.test# 日志文件
*.log
logs# 测试覆盖率
coverage
.nyc_output# 临时文件
*.tmp
.cache
📌 关键点解释：
node_modules：依赖会在容器内重新安装，不需要复制本地的dist：构建产物会在容器内生成，不需要复制本地的.git、.vscode等：开发环境文件，和运行无关.env*：敏感环境变量文件，建议不要直接打包进镜像
2️⃣ Dockerfile
Dockerfile 定义了镜像的构建过程。这里采用 多阶段构建，先用 Node 构建前端，再用 Nginx 提供静态资源。
完整文件如下：
# -------------------------------
# 构建阶段：使用 Node 构建 Vue3 前端
# -------------------------------
FROM node:20-alpine AS buildWORKDIR /app# 设置 npm 镜像源和 Node.js 内存限制（提前设置）
RUN npm config set registry https://registry.npmmirror.com/
ENV NODE_OPTIONS="--max-old-space-size=4096"# 先复制依赖文件，利用 Docker 缓存（重要优化）
COPY package*.json ./# 安装依赖
RUN npm install# 再复制源码（不包括 node_modules，通过 .dockerignore 排除）
COPY . .# 构建
RUN npm run build# -------------------------------
# 运行阶段：使用 Nginx 提供静态资源
# -------------------------------
FROM nginx:1.28.0-alpineWORKDIR /usr/share/nginx/htmlRUN rm -rf ./*COPY --from=build /app/dist/ ./
COPY deploy/nginx.conf /etc/nginx/nginx.confEXPOSE 8080HEALTHCHECK --interval=30s --timeout=5s --retries=3 \CMD wget -qO- http://localhost:8080/ || exit 1CMD ["nginx", "-g", "daemon off;"]
📌 关键点解释：
- 多阶段构建：
node:20-alpine用来构建，nginx:alpine用来运行，避免 Node 依赖进入最终镜像 COPY package*.json ./+RUN npm install：利用 Docker 缓存机制，加快构建速度ENV NODE_OPTIONS="--max-old-space-size=4096"：避免大项目构建时内存不足COPY --from=build /app/dist/ ./：只复制构建产物，镜像更小更干净HEALTHCHECK：容器健康检查，确保服务正常
3️⃣ deploy/nginx.conf
Nginx 配置文件，负责提供静态资源、处理路由、反向代理 API。
完整文件如下：
user nginx;
worker_processes auto;error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;events {worker_connections 10240;multi_accept on;
}http {include /etc/nginx/mime.types;default_type application/octet-stream;# 日志格式log_format main '$remote_addr - $remote_user [$time_local] "$request" ''$status $body_bytes_sent "$http_referer" ''"$http_user_agent" "$http_x_forwarded_for"';access_log /var/log/nginx/access.log main;sendfile on;tcp_nopush on;tcp_nodelay on;keepalive_timeout 65;types_hash_max_size 2048;# -------------------------# 安全与优化配置# -------------------------server_tokens off; # 隐藏 Nginx 版本号client_max_body_size 10M; # 限制上传大小client_body_timeout 12; # 请求体超时client_header_timeout 12; # 请求头超时keepalive_requests 1000; # 单连接最大请求数# Gzip 压缩gzip on;gzip_min_length 1024;gzip_comp_level 6;gzip_types text/plain text/css application/javascript application/json application/xml text/xml image/svg+xml;gzip_vary on;gzip_proxied any;gzip_disable "msie6";# -------------------------# HTTPS 配置（生产环境推荐）# -------------------------server {listen 8080; # 容器内监听 8080，避免 root 权限server_name _;root /usr/share/nginx/html;index index.html;# Vue3 前端路由 history 模式location / {try_files $uri $uri/ /index.html;}# 反向代理后端 API# location /api/ {# proxy_pass http://backend:48080/; # 修改为后端服务地址# proxy_http_version 1.1;# proxy_set_header Upgrade $http_upgrade;# proxy_set_header Connection "upgrade";# proxy_set_header Host $host;# proxy_set_header X-Real-IP $remote_addr;# proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;# proxy_set_header X-Forwarded-Proto $scheme;# }# 静态资源缓存策略location ~* \.(?:ico|css|js|gif|jpe?g|png|woff2?|eot|ttf|svg)$ {expires 6M;access_log off;add_header Cache-Control "public";}# 错误页面error_page 404 /index.html;error_page 500 502 503 504 /50x.html;location = /50x.html {root /usr/share/nginx/html;}}
}
📌 关键点解释：
try_files $uri $uri/ /index.html;：解决 Vue Router history 模式刷新 404 问题gzip：开启压缩，减少传输体积expires 6M;：静态资源缓存 6 个月，提升性能proxy_pass：可选反向代理后端 API（需要时取消注释）error_page 404 /index.html;：前端路由兜底
4️⃣ 构建与运行
在项目根目录执行：
# 构建镜像
docker build -t vue3-app .# 运行容器
docker run -d -p 8080:8080 --name vue3-app vue3-app
然后访问 👉 http://localhost:8080 即可看到前端页面。
5️⃣ 总结
通过这三个文件，我们实现了：
- 干净高效的镜像构建（多阶段构建 +
.dockerignore） - 生产级 Nginx 配置（gzip、缓存、路由、反向代理）
- 可扩展的部署方案（支持 CI/CD、K8s 等场景）