Docker Compose 部署 VitePress 项目

VitePress 是由 Vue 团队开发的静态站点生成器，结合 Docker Compose 可以轻松实现项目的容器化部署。下面将详细介绍如何使用 Docker Compose 部署 VitePress 项目，包括基础配置、优化技巧和自动化部署方案。

1. 项目初始化与准备

1.1 创建 VitePress 项目

首先确保已安装 Node.js 18+和 Docker 环境，然后初始化 VitePress 项目：

mkdir my-vitepress && cd my-vitepress
npm init -y
npm install -D vitepress
pnpm vitepress init  # 使用交互式向导初始化项目

初始化完成后，项目目录结构通常如下：

.
├── docs
│   ├── .vitepress
│   │   └── config.js
│   ├── index.md
│   └── api-examples.md
├── package.json
└── pnpm-lock.yaml

1.2 修改构建输出目录

默认情况下，VitePress 将构建输出到.vitepress/dist，但为了方便 Docker 部署，建议修改为根目录下的dist文件夹。在docs/.vitepress/config.js中添加：

import { defineConfig } from "vitepress";
import { fileURLToPath } from "node:url";

export default defineConfig({
  // 其他配置...
  outDir: fileURLToPath(new URL("../dist", import.meta.url)),
});

2. Docker 相关配置

2.1 创建 Dockerfile

在项目根目录创建Dockerfile，使用多阶段构建优化镜像大小：

# 构建阶段
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm --registry=http://mirrors.cloud.tencent.com/npm/ && \
    pnpm install --registry=http://mirrors.cloud.tencent.com/npm/
COPY . .
RUN pnpm run docs:build

# 生产阶段
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

2.2 创建 Nginx 配置

创建nginx.conf文件处理 VitePress 的路由：

server {
    listen 80;
    server_name localhost;

    location / {
        root /usr/share/nginx/html;
        try_files $uri $uri/ /index.html;
        index index.html index.htm;
    }

    # 启用gzip压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}

2.3 创建.dockerignore

避免不必要的文件被复制到镜像中：

node_modules
.git
.vitepress/cache
dist
.idea
*.md
Dockerfile
nginx.conf
.dockerignore

3. Docker Compose 配置

3.1 基础 docker-compose.yml

创建docker-compose.yml文件：

version: "3.8"
services:
  vitepress:
    build: .
    container_name: my-vitepress
    ports:
      - "8080:80"
    environment:
      - TZ=Asia/Shanghai
    networks:
      - vitepress-net
    restart: unless-stopped

networks:
  vitepress-net:
    driver: bridge

3.2 启动项目

运行以下命令构建并启动容器：

docker-compose up --build -d

访问http://localhost:8080即可查看部署的 VitePress 站点。

4. 高级配置选项

4.1 开发环境热更新配置

对于开发环境，可以配置卷挂载实现代码热更新：

services:
  vitepress:
    build: .
    ports:
      - "5173:5173"
    volumes:
      - .:/app
      - /app/node_modules
    command: pnpm run docs:dev
    environment:
      - NODE_ENV=development

4.2 多服务组合部署

如果需要结合后端 API 服务，可以扩展 docker-compose 配置：

services:
  vitepress:
    # ...原有配置
    depends_on:
      - api-service

  api-service:
    image: my-api-image
    ports:
      - "3000:3000"
    networks:
      - vitepress-net

5. 生产环境优化建议

1. 镜像优化：

   • 使用node:alpine和nginx:alpine等轻量级基础镜像
   • 多阶段构建减少最终镜像大小
   • 清理构建缓存：RUN npm cache clean --force

2. 性能优化：

   • 启用 Nginx 的 gzip 压缩
   • 配置静态资源缓存策略
   • 使用 CDN 加速静态资源

3. 安全优化：

   • 定期更新基础镜像版本
   • 使用非 root 用户运行容器
   • 配置适当的 Nginx 安全头

6. 自动化部署方案

6.1 GitHub Actions 自动化

在.github/workflows/deploy.yml中配置：

name: Deploy VitePress
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: pnpm install
      - run: pnpm run docs:build
      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: user/app:latest
          file: ./Dockerfile

6.2 服务器端自动更新

在服务器上设置 webhook 或定时任务，当检测到新镜像时自动拉取并重启容器：

docker-compose pull && docker-compose up -d --force-recreate

7. 常见问题解决

1. 路由 404 问题：

   • 确保 Nginx 配置中包含try_files $uri $uri/ /index.html
   • 检查 VitePress 的base配置是否正确

2. 构建失败：

   • 检查 Node.js 版本是否符合要求(建议 18+)
   • 清理缓存后重试：rm -rf node_modules && rm pnpm-lock.yaml

3. 跨域问题：

   • 开发环境可在vitepress.config.js中配置代理
   • 生产环境通过 Nginx 统一转发 API 请求

通过以上步骤，你可以轻松地使用 Docker Compose 部署 VitePress 项目，并根据需要扩展配置。这种部署方式提供了环境一致性、易于维护和可扩展性等优势，特别适合团队协作和持续交付场景。