部署指南

本指南将帮助您将VitePress开发指南部署到各种平台。

构建项目

在部署之前，首先需要构建项目：

# 安装依赖
npm install

# 构建生产版本
npm run build

构建完成后，静态文件将生成在 .vitepress/dist 目录中。

GitHub Pages 部署

自动部署

创建 .github/workflows/deploy.yml 文件：

name: Deploy VitePress site to Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: npm
      
      - name: Setup Pages
        uses: actions/configure-pages@v4
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build with VitePress
        run: npm run build
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: .vitepress/dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

配置 GitHub Pages

1. 在 GitHub 仓库设置中启用 Pages
2. 选择 "GitHub Actions" 作为部署源
3. 推送代码到 main 分支即可自动部署

Vercel 部署

一键部署

手动部署

1. 在 Vercel 中导入 GitHub 仓库
2. 配置构建设置：
   • Framework Preset: Vite
   • Build Command: npm run build
   • Output Directory: .vitepress/dist
3. 部署完成

Netlify 部署

配置文件

创建 netlify.toml 文件：

[build]
  command = "npm run build"
  publish = ".vitepress/dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

部署步骤

1. 连接 GitHub 仓库到 Netlify
2. 配置构建设置（如上）
3. 部署完成

自定义服务器部署

Nginx 配置

server {
    listen 80;
    server_name mmwk.cn www.mmwk.cn;
    
    root /var/www/mmwk-site;
    index index.html;
    
    # 处理 SPA 路由
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    
    # Gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}

Docker 部署

创建 Dockerfile：

FROM node:18-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/.vitepress/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

构建和运行：

# 构建镜像
docker build -t mmwk-site .

# 运行容器
docker run -p 80:80 mmwk-site

域名配置

自定义域名

1. 在 public 目录下创建 CNAME 文件：

   mmwk.cn

2. 配置 DNS 记录：

   • A 记录指向服务器 IP
   • 或 CNAME 记录指向部署平台域名

SSL 证书

推荐使用 Let's Encrypt 免费证书：

# 安装 Certbot
sudo apt install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d mmwk.cn -d www.mmwk.cn

性能优化

构建优化

在 vite.config.ts 中配置：

import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'element-plus': ['element-plus'],
          'vue': ['vue']
        }
      }
    }
  }
})

CDN 加速

配置静态资源 CDN：

// .vitepress/config.ts
export default defineConfig({
  vite: {
    build: {
      assetsDir: 'assets'
    }
  }
})

监控和分析

Google Analytics

在配置文件中添加：

head: [
  [
    'script',
    { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID' }
  ],
  [
    'script',
    {},
    `window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', 'GA_MEASUREMENT_ID');`
  ]
]

错误监控

集成 Sentry 进行错误监控：

// .vitepress/theme/index.ts
import * as Sentry from "@sentry/vue"

export default {
  enhanceApp({ app }) {
    Sentry.init({
      app,
      dsn: "YOUR_SENTRY_DSN"
    })
  }
}

故障排除

常见问题

1. 路由 404 错误

   • 确保服务器配置了 SPA 回退
   • 检查 base 路径配置

2. 静态资源加载失败

   • 检查 publicPath 配置
   • 确认文件路径正确

3. 构建失败

   • 检查 Node.js 版本（推荐 18+）
   • 清除 node_modules 重新安装

调试技巧

# 本地预览构建结果
npm run preview

# 检查构建输出
npm run build -- --debug

# 分析包大小
npm run build -- --analyze

---

部署完成后，您的VitePress开发指南就可以在 https://mmwk.cn 访问了！