Vue3 前端项目 Docker 容器化部署教程

本教程将带你从零开始，使用 Docker + Nginx 将一个 Vue3 前端项目打包并运行在容器中。我们会用到三个关键文件：

.dockerignore ------ 控制哪些文件不被复制进镜像
Dockerfile ------ 定义构建和运行镜像的步骤
deploy/nginx.conf ------ 配置 Nginx 作为静态资源服务器

最终效果：

前端代码会在容器中构建
构建产物交由 Nginx 提供服务
支持 Vue Router history 模式
可选反向代理后端 API
启用 gzip 压缩和缓存优化

📂 项目结构示例

bash 复制代码

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 在构建镜像时不要复制哪些文件，避免无用文件进入镜像，减小体积并加快构建速度。

完整文件如下：

dockerignore 复制代码

# 依赖目录
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 提供静态资源。

完整文件如下：

dockerfile 复制代码

# -------------------------------
# 构建阶段：使用 Node 构建 Vue3 前端
# -------------------------------
FROM node:20-alpine AS build

WORKDIR /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-alpine

WORKDIR /usr/share/nginx/html

RUN rm -rf ./*

COPY --from=build /app/dist/ ./
COPY deploy/nginx.conf /etc/nginx/nginx.conf

EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD wget -qO- http://localhost:8080/ || exit 1

CMD ["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。

完整文件如下：

nginx 复制代码

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️⃣ 构建与运行

在项目根目录执行：

bash 复制代码

# 构建镜像
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 等场景）

Vue3 前端项目 Docker 容器化部署教程

📂 项目结构示例

🔑 说明

1️⃣ .dockerignore

2️⃣ Dockerfile

3️⃣ deploy/nginx.conf

4️⃣ 构建与运行

5️⃣ 总结

1️⃣ `.dockerignore`

2️⃣ `Dockerfile`

3️⃣ `deploy/nginx.conf`