部署指南

本指南将介绍如何将你的 VitePress 站点部署到不同的托管平台。

🚀 极速部署 (一键部署)

如果你想快速体验，可以使用以下平台的一键部署功能：

• EdgeOne Pages: 立即部署 (连接 GitHub 即可)
• Vercel:
• Netlify:

1. 构建项目

在部署之前，你首先需要构建项目生成静态文件：

# 使用 bun
bun run docs:build

# 或使用 npm
npm run docs:build

构建完成后，生成的静态文件位于 docs/.vitepress/dist 目录。

2. 部署平台

Vercel 是托管 VitePress 站点的首选平台之一，配置简单且性能卓越。

方式一：连接 Git 仓库 (推荐)

1. 登录 Vercel。
2. 点击 Add New -> Project。
3. 导入你的 GitHub 仓库。
4. Vercel 会自动检测到 VitePress 项目。
5. 确保 Output Directory 设置为 docs/.vitepress/dist。
6. 点击 Deploy。

方式二：使用 Vercel CLI

# 安装并部署
npx vercel deploy --prod --dir docs/.vitepress/dist

3. GitHub Actions 示例

如果你想自定义 GitHub Actions 部署流程，可以参考以下配置：

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      - run: bun install
      - run: bun run docs:build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

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

4. 常见问题

404 错误

如果在刷新页面时出现 404，请确保托管平台已正确配置单页应用 (SPA) 的回退路由，或者你的 VitePress 生成的是全量静态 HTML（默认情况）。

缓存刷新

在使用 CDN 加速（如 EdgeOne）时，更新部署后可能需要几分钟才能在全球节点生效。你可以在各平台控制台手动刷新缓存。