部署到线上

将你的 VitePress 站点部署到线上，让所有人都能访问。

构建生产版本

执行构建

npm run build

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

本地预览

npm run preview

访问 http://localhost:4173 预览构建结果。

部署到 GitHub Pages

1. 配置 base

// .vitepress/config.mts
export default defineConfig({
  base: '/your-repo-name/'  // GitHub 仓库名
})

2. 创建工作流

创建 .github/workflows/deploy.yml：

name: Deploy to GitHub 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: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build
        run: npm run build
      
      - name: Upload artifact
        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:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

3. 启用 GitHub Pages

1. 进入仓库 Settings > Pages
2. Source 选择 "GitHub Actions"
3. 推送代码触发部署

部署到 Vercel

方式一：Vercel CLI

# 安装 CLI
npm i -g vercel

# 部署
vercel

方式二：Git 集成

1. 访问 vercel.com
2. 导入 GitHub 仓库
3. 配置项目：
   • Framework Preset: VitePress
   • Build Command: npm run build
   • Output Directory: docs/.vitepress/dist

vercel.json 配置

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

部署到 Netlify

方式一：拖拽部署

1. 运行 npm run build
2. 访问 app.netlify.com
3. 拖拽 dist 目录到部署区域

方式二：Git 集成

1. 连接 GitHub 仓库
2. 配置构建设置：
   • Build Command: npm run build
   • Publish Directory: docs/.vitepress/dist

netlify.toml

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

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

部署到 Cloudflare Pages

1. 登录 Cloudflare Dashboard
2. 进入 Pages > Create a project
3. 连接 GitHub 仓库
4. 配置构建：
   • Build Command: npm run build
   • Build output directory: docs/.vitepress/dist

自定义域名

添加 CNAME 文件

创建 docs/public/CNAME：

docs.example.com

配置 DNS

根据平台要求配置 DNS 记录：

平台	类型	值
GitHub Pages	CNAME	username.github.io
Vercel	A	76.76.21.21
Netlify	CNAME	your-site.netlify.app

HTTPS 配置

大多数平台自动提供 HTTPS 证书。如果需要自定义：

export default defineConfig({
  head: [
    ['meta', { 'http-equiv': 'Content-Security-Policy', content: 'upgrade-insecure-requests' }]
  ]
})

环境变量

在构建中使用

export default defineConfig({
  base: process.env.BASE_URL || '/'
})

GitHub Actions

env:
  BASE_URL: /${{ github.event.repository.name }}/

Vercel

在项目设置中添加环境变量。

部署检查清单

部署前检查：

• [ ] 构建无错误
• [ ] 本地预览正常
• [ ] base 路径配置正确
• [ ] 图片资源路径正确
• [ ] 自定义域名 DNS 配置
• [ ] HTTPS 证书生效

常见问题

页面 404

检查 base 配置是否正确：

// GitHub Pages 需要设置
base: '/repo-name/'

资源加载失败

确保资源路径使用相对路径或正确的绝对路径。

路由不工作

确保服务器配置了 SPA 回退（大多数平台自动支持）。

下一步

恭喜！你已经完成了 VitePress 入门教程。继续探索：

• 自定义主题颜色 - 美化站点
• 添加博客功能 - 博客功能
• 集成评论系统 - 互动功能

进阶挑战

挑战 1：配置自定义域名

将你的站点绑定到自定义域名，并启用 HTTPS。

查看提示

1. 在域名提供商处添加 DNS 记录（CNAME 或 A 记录）
2. 在 docs/public/ 目录下创建 CNAME 文件，内容为你的域名
3. 在部署平台配置自定义域名
4. 等待 SSL 证书自动签发

挑战 2：配置 CI/CD 自动部署

配置 GitHub Actions 实现推送代码后自动构建部署。

查看提示

参考本文「部署到 GitHub Pages」章节的工作流配置，确保：

• permissions 正确设置
• 构建命令和输出路径匹配
• 触发分支与你的主分支一致

挑战 3：多环境部署

同时部署到 GitHub Pages 和 Vercel，验证不同平台的构建结果。

查看提示

• GitHub Pages 需要配置 base 路径
• Vercel 可以通过 vercel.json 覆盖配置
• 使用环境变量区分不同平台的配置

部署检查清单

部署前确认以下事项：

• [ ] 构建无错误（npm run build 成功）
• [ ] 本地预览正常（npm run preview 验证）
• [ ] base 路径配置正确（GitHub Pages 需要）
• [ ] 图片和静态资源路径正确
• [ ] 自定义域名 DNS 已配置
• [ ] HTTPS 证书已生效
• [ ] 页面跳转和路由正常工作
• [ ] 搜索功能在生产环境可用

常见问题

构建后页面空白

通常是 base 路径配置问题。如果你部署到子路径（如 username.github.io/repo/），必须设置：

export default defineConfig({
  base: '/repo-name/'
})

图片在部署后无法显示

确保图片使用绝对路径引用（以 / 开头），且存放在 public 目录中：

<!-- ✅ 正确 -->
![Logo](/images/logo.png)

<!-- ❌ 错误：相对路径可能失效 -->
![Logo](./images/logo.png)

部署后路由 404

单页应用需要服务器配置回退到 index.html。大多数平台（Vercel、Netlify）自动支持，GitHub Pages 也通过工作流自动处理。

如果使用自定义服务器，添加重写规则：

# Nginx 配置
location / {
  try_files $uri $uri/ /index.html;
}

# Apache .htaccess
RewriteEngine On
RewriteBase /
RewriteRule ^index\.html$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.html [L]

部署平台如何选择？

平台	优点	适合场景
GitHub Pages	免费、与 GitHub 深度集成	开源项目文档
Vercel	部署快、自动预览、全球 CDN	团队项目、需要预览
Netlify	功能丰富、表单处理	需要服务端功能
Cloudflare Pages	全球边缘节点、速度快	全球访问场景