VitePress 学习指南

主题

部署平台 ​

选择合适的部署平台，将你的 VitePress 站点发布上线。

平台对比 ​

平台免费额度国内访问自定义域名CI/CD特点
Vercel100GB/月⚠️ 较慢✅✅最流行，预览部署
Netlify100GB/月⚠️ 较慢✅✅功能丰富
GitHub Pages100GB/月⚠️ 较慢✅✅免费集成 GitHub
Cloudflare Pages无限✅ 快速✅✅全球 CDN，国内快
腾讯云 EdgeOne有免费额度✅ 快速✅✅国内企业首选
Railway$5/月额度✅ 快速✅✅现代化托管
Zeabur有免费额度✅ 快速✅✅简单易用

选择建议 ​

场景推荐原因
个人博客Vercel免费、简单
开源项目GitHub Pages免费集成
国内用户Cloudflare / EdgeOne访问快速
企业站点自托管 / EdgeOne可控性高
快速部署Zeabur简单易用
多环境部署Netlify预览部署完善

通用构建配置 ​

所有平台的核心配置都相同：

配置项值
Build Commandnpm run docs:build
Output Directorydocs/.vitepress/dist
Node.js 版本18+
Install Commandnpm ci

Vercel ​

最流行的前端部署平台，零配置部署 VitePress。

自动部署 ​

  1. 访问 Vercel 使用 GitHub 登录
  2. 点击 "New Project" 导入仓库
  3. Framework Preset 选择 VitePress（自动识别）
  4. 点击 "Deploy" 完成部署

vercel.json 配置 ​

VitePress 使用 clean URLs，需要配置路由重写：

json
{
  "cleanUrls": true,
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    },
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "X-XSS-Protection", "value": "1; mode=block" }
      ]
    }
  ]
}

环境变量 ​

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

变量名说明
NODE_VERSION20
VITE_API_URLAPI 地址

预览部署 ​

Vercel 自动为每个 PR 创建预览部署，方便团队审阅。

GitHub Pages ​

免费、稳定，与 GitHub 仓库深度集成。

GitHub Actions 部署 ​

yaml
# .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
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run docs:build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

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

子路径部署 ​

部署到 https://username.github.io/repo/ 时需要配置 base：

ts
// .vitepress/config.mts
export default defineConfig({
  base: '/repo-name/'
})

自定义域名 ​

  1. 在仓库 Settings > Pages > Custom domain 添加域名
  2. 在域名 DNS 添加 CNAME 记录指向 username.github.io
  3. 勾选 "Enforce HTTPS"

Cloudflare Pages ​

全球 CDN 加速，国内访问速度优秀。

自动部署 ​

  1. 访问 Cloudflare Pages 连接 Git 仓库
  2. 配置构建命令和输出目录
  3. 点击 "Save and Deploy"

自定义构建配置 ​

配置项值
Build commandnpm run docs:build
Build output directorydocs/.vitepress/dist
Node.js version20（环境变量 NODE_VERSION）

_redirects 配置 ​

VitePress 使用 clean URLs，需要配置重定向：

# public/_redirects
# 处理不带 .html 后缀的 URL
/posts/* /posts/*/:splat 200

_headers 配置 ​

# public/_headers
/assets/*
  Cache-Control: public, max-age=31536000, immutable
/*
  X-Content-Type-Options: nosniff
  X-Frame-Options: DENY
  X-XSS-Protection: 1; mode=block

预览部署 ​

Cloudflare Pages 为每个 PR 自动创建预览部署，URL 格式为 <commit-hash>.<project>.pages.dev。

Netlify ​

功能丰富的前端部署平台，支持表单处理和 Serverless Functions。

自动部署 ​

  1. 访问 Netlify 连接 Git 仓库
  2. 配置构建命令和输出目录
  3. 点击 "Deploy site"

netlify.toml 配置 ​

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

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[headers]]
  for = "/*"
  [headers.values]
    X-Content-Type-Options = "nosniff"
    X-Frame-Options = "DENY"
    X-XSS-Protection = "1; mode=block"
    Referrer-Policy = "strict-origin-when-cross-origin"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200
  conditions = { Language = ["en"] }

表单处理 ​

Netlify 内置表单处理，无需后端：

html
<form name="contact" method="POST" data-netlify="true">
  <input type="text" name="name" required />
  <input type="email" name="email" required />
  <textarea name="message" required></textarea>
  <button type="submit">提交</button>
</form>

腾讯云 EdgeOne ​

国内企业首选，国内访问速度极快。

部署步骤 ​

  1. 登录 EdgeOne 控制台
  2. 创建站点并绑定域名
  3. 配置源站或使用 EdgeOne Pages 直接部署
  4. 配置 SSL 证书

CNB 自动部署 ​

项目使用 CNB (Cloud Native Build) 自动化部署到 EdgeOne：

yaml
# .cnb.yml
main:
  push:
    - docker:
        image: node:20-alpine
      stages:
        - name: build
          script:
            - npm ci
            - npm run docs:build
        - name: deploy
          script:
            - npx @cloudbase/cli deploy --dist docs/.vitepress/dist

Railway ​

现代化托管平台，支持多服务部署。

部署步骤 ​

  1. 访问 Railway 连接 Git 仓库
  2. 配置构建命令和输出目录
  3. 自动部署

railway.json 配置 ​

json
{
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm run docs:build"
  },
  "deploy": {
    "startCommand": "npx serve docs/.vitepress/dist -s -l $PORT"
  }
}

Zeabur ​

简单易用的部署平台，自动检测项目类型。

部署步骤 ​

  1. 访问 Zeabur 导入 Git 仓库
  2. 自动检测 VitePress 项目并配置
  3. 一键部署

自托管服务器 ​

适合需要完全控制的场景。

Nginx 配置 ​

nginx
server {
    listen 80;
    server_name your-site.com;
    root /var/www/vitepress/dist;

    # 安全头
    add_header X-Content-Type-Options nosniff;
    add_header X-Frame-Options DENY;
    add_header X-XSS-Protection "1; mode=block";
    add_header Referrer-Policy "strict-origin-when-cross-origin";

    # Gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml text/javascript image/svg+xml;
    gzip_min_length 1000;

    # 静态资源长缓存
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # SPA 路由回退
    location / {
        try_files $uri $uri/ $uri.html /index.html;
    }

    # 404 页面
    error_page 404 /404.html;
}

# HTTPS 配置
server {
    listen 443 ssl http2;
    server_name your-site.com;

    ssl_certificate /etc/letsencrypt/live/your-site.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-site.com/privkey.pem;

    # ... 其他配置同上
}

Docker 部署 ​

多阶段构建 ​

dockerfile
# 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;"]

Docker Compose ​

yaml
# docker-compose.yml
version: '3.8'
services:
  vitepress:
    build: .
    ports:
      - "8080:80"
    restart: unless-stopped

自动化部署脚本 ​

bash
#!/bin/bash
# deploy.sh
set -e

echo "📦 拉取最新代码..."
git pull origin main

echo "🏗️ 构建站点..."
npm ci
npm run docs:build

echo "🚀 重启 Docker 容器..."
docker compose up -d --build

echo "✅ 部署完成！"

CDN 加速 ​

推荐使用国内 CDN 加速静态资源：

CDN特点
Cloudflare免费，全球节点
腾讯云 CDN国内加速效果好
阿里云 CDN稳定，节点多
七牛云免费额度大

部署检查清单 ​

部署前确保以下项目已完成：

内容检查 ​

  • [ ] 所有页面链接有效
  • [ ] 图片资源正确引用
  • [ ] 搜索功能正常
  • [ ] 多语言页面完整

性能检查 ​

  • [ ] 构建无错误无警告
  • [ ] 页面 Lighthouse 评分 > 90
  • [ ] 图片已压缩优化
  • [ ] 启用 Gzip/Brotli 压缩

安全检查 ​

  • [ ] HTTPS 已配置
  • [ ] 安全头已添加
  • [ ] 无敏感信息泄露
  • [ ] 依赖无已知漏洞

SEO 检查 ​

  • [ ] Sitemap 已生成
  • [ ] robots.txt 已配置
  • [ ] Meta 标签完整
  • [ ] Canonical URL 正确

常见问题 ​

部署后页面 404？ ​

常见原因：

  1. base 路径不正确：子路径部署时需设置 base
  2. 路由模式不匹配：确保服务器配置了 SPA 回退
  3. 输出目录不正确：确认部署的是 docs/.vitepress/dist

静态资源加载失败？ ​

  1. 路径问题：检查 base 配置与实际部署路径是否一致
  2. 缓存问题：清除 CDN 缓存或使用新文件名
  3. CORS 问题：跨域资源需要配置 CORS 头

构建超时？ ​

  1. 依赖过多：检查是否有不必要的依赖
  2. 构建缓存：配置构建缓存加速
  3. Node 版本：使用 Node 20+ 提升构建速度

国内访问慢？ ​

  1. 选择 Cloudflare Pages 或 EdgeOne 部署
  2. 使用国内 CDN 加速
  3. 考虑自托管服务器

进阶配置 ​

Docker 完整配置、EdgeOne 部署、CDN 加速、环境变量、部署检查清单等：

相关链接 ​

📖 相关文章推荐

部署与发布
高级部署

贡献者

加载中...

想要成为贡献者？

在 CNB 上参与贡献

Copyright © 2016 - 2026 VitePress 学习指南