部署与发布

完成文档编写后，需要将站点部署到服务器上。

构建站点

构建命令

npm run docs:build

构建产物位于 docs/.vitepress/dist/ 目录。

预览构建结果

npm run docs:preview

默认访问 http://localhost:4173。

构建配置

export default defineConfig({
  // 基础路径（部署到子目录时需要配置）
  base: '/docs/',
  
  // 输出目录
  outDir: '../dist',
  
  // 缓存目录
  cacheDir: '.vitepress/cache'
})

静态托管

GitHub Pages

1. 创建 .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:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - uses: pnpm/action-setup@v3
        with:
          version: 8
      
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      
      - run: pnpm install
      
      - name: Build
        run: pnpm docs:build
      
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

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

2. 在仓库设置中启用 GitHub Pages，选择 GitHub Actions 作为源。

Netlify

1. 创建 netlify.toml：

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

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

2. 连接 GitHub 仓库到 Netlify。

Vercel

1. 创建 vercel.json：

{
  "buildCommand": "npm run docs:build",
  "outputDirectory": "docs/.vitepress/dist"
}

2. 导入项目到 Vercel。

Cloudflare Pages

1. 构建配置：

   • 构建命令：npm run docs:build
   • 输出目录：docs/.vitepress/dist

2. 连接 GitHub 仓库。

腾讯云 EdgeOne Pages

EdgeOne Pages 是腾讯云提供的边缘计算托管平台，支持全球加速和边缘渲染。

方式一：通过 CNB 云开发部署

本项目使用 CNB（cnb.cool）云开发平台进行部署：

1. 项目配置：确保 package.json 中有正确的构建命令：

{
  "scripts": {
    "docs:build": "vitepress build docs"
  }
}

2. CNB 云构建配置：在项目根目录创建 cnb.yml：

# cnb.yml - CNB 云构建配置
version: 1

build:
  commands:
    - npm ci
    - npm run docs:build
  
  output:
    path: docs/.vitepress/dist

deploy:
  provider: edgeone
  # EdgeOne Pages 配置

3. 部署流程：
   • 代码推送到 CNB 仓库（cnb.cool）
   • CNB 云构建自动触发
   • 构建产物自动发布到 EdgeOne Pages

方式二：直接使用 EdgeOne Pages

1. 登录 EdgeOne Pages 控制台

2. 创建项目并连接 Git 仓库

3. 构建配置：

   • 构建命令：npm run docs:build
   • 输出目录：docs/.vitepress/dist
   • Node.js 版本：18 或 20

4. 配置域名和 SSL 证书

EdgeOne Pages 配置文件

创建 edgeone.json 进行高级配置：

{
  "name": "vitepress-docs",
  "build": {
    "command": "npm run docs:build",
    "output": "docs/.vitepress/dist"
  },
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/$1"
    }
  ],
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    }
  ]
}

边缘函数配置

EdgeOne 支持边缘函数处理请求：

// edge-functions/redirect.js
export default function handler(request) {
  const url = new URL(request.url)
  
  // 旧链接重定向
  if (url.pathname.startsWith('/old-path/')) {
    const newPath = url.pathname.replace('/old-path/', '/new-path/')
    return Response.redirect(new URL(newPath, url.origin), 301)
  }
  
  return fetch(request)
}

EdgeOne Pages 优势

特性	说明
全球加速	边缘节点遍布全球，访问速度快
自动 HTTPS	免费 SSL 证书自动配置
预渲染支持	支持 SSR 和 SSG 混合部署
防护能力	内置 DDoS 防护和 WAF
日志分析	完善的访问日志和性能分析

Docker 部署

创建 Dockerfile

# 构建阶段
FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run docs:build

# 生产阶段
FROM nginx:alpine

COPY --from=builder /app/docs/.vitepress/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

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

Nginx 配置

# nginx.conf
server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ $uri.html /index.html;
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
}

构建和运行

# 构建镜像
docker build -t vitepress-docs .

# 运行容器
docker run -d -p 80:80 vitepress-docs

传统服务器部署

构建并上传

# 构建
npm run docs:build

# 使用 rsync 上传
rsync -avz docs/.vitepress/dist/ user@server:/var/www/html/

Nginx 配置

server {
    listen 80;
    server_name example.com;
    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ $uri.html /index.html;
    }

    # 启用 gzip
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml;

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

CDN 加速

配置 CDN

1. 将静态资源上传到对象存储（如 AWS S3、阿里云 OSS）
2. 配置 CDN 域名
3. 修改 base 配置：

export default defineConfig({
  base: 'https://cdn.example.com/'
})

资源哈希

VitePress 自动为打包文件添加内容哈希，确保缓存正确失效。

环境变量

构建时环境变量

# .env.production
VITE_API_URL=https://api.example.com

在代码中使用：

const apiUrl = import.meta.env.VITE_API_URL

不同环境配置

// docs/.vitepress/config.mts
export default defineConfig({
  title: import.meta.env.VITE_SITE_TITLE || '默认标题'
})

部署检查清单

• [ ] 配置正确的 base 路径
• [ ] 设置正确的站点标题和描述
• [ ] 添加 favicon 和 logo
• [ ] 配置 404 页面
• [ ] 启用 gzip 压缩
• [ ] 配置静态资源缓存
• [ ] 测试所有链接
• [ ] 检查移动端适配
• [ ] 配置 HTTPS
• [ ] 设置自定义域名

相关主题

• 更多部署平台 — Railway、Render、Zeabur 等
• 部署生态集成 — Docker、EdgeOne、CDN 加速
• 教程：部署站点 — 手把手部署教程

下一步

前往 性能优化 学习如何优化站点性能。