实施指南

Cloudflare Pages部署配置

前置条件

1. 账户准备

• Cloudflare账户（免费版即可）
• GitHub或GitLab账户（用于代码托管）

2. 本地开发环境

• Node.js 18+（推荐20+）
• npm/pnpm/yarn包管理器
• Git版本控制

3. 验证本地环境

# 检查Node.js版本
node -v  # 应输出 v20.x.x 或更高

# 检查npm版本
npm -v

构建配置

方式一：通过Cloudflare Dashboard配置

1. 创建Cloudflare Pages项目

   • 登录Cloudflare Dashboard
   • 进入 Workers & Pages → Create application → Pages
   • 选择 “Connect to Git”

2. 连接Git仓库

   • 授权GitHub/GitLab访问
   • 选择包含VitePress项目的仓库

3. 配置构建设置

4. 部署
   • 点击 “Save and Deploy”
   • 等待构建完成（通常1-3分钟）

方式二：使用Wrangler CLI部署

# 安装Wrangler
npm install -g wrangler

# 登录Cloudflare
wrangler login

# 构建项目
npm run docs:build

# 部署到Cloudflare Pages
wrangler pages deploy docs/.vitepress/dist --project-name=my-docs

环境变量

在Cloudflare Pages Dashboard中设置环境变量：

Settings → Environment variables

注意：VitePress通常不需要额外的环境变量，除非使用了需要API密钥的插件。

VitePress配置示例

项目结构

推荐的VitePress项目结构：

my-docs/
├── .vitepress/
│   ├── config.mts          # 主配置文件（推荐TypeScript）
│   ├── theme/
│   │   ├── index.ts        # 主题入口
│   │   ├── custom.css      # 自定义样式
│   │   └── components/     # 自定义组件
│   └── cache/              # 构建缓存（自动生成）
├── public/
│   ├── favicon.ico
│   └── images/
├── guide/
│   ├── index.md
│   ├── getting-started.md
│   └── advanced.md
├── api/
│   ├── index.md
│   └── reference.md
├── index.md                # 首页
├── package.json
└── .gitignore

配置文件

完整配置示例 (.vitepress/config.mts)

import { defineConfig } from 'vitepress'

export default defineConfig({
  // 站点元数据
  title: '我的文档站',
  description: '基于VitePress构建的专业文档网站',
  lang: 'zh-CN',
  
  // 构建配置
  srcDir: '.',
  outDir: '.vitepress/dist',
  cleanUrls: true,  // 干净URL（无.html后缀）
  lastUpdated: true,  // 显示最后更新时间
  
  // Head标签配置
  head: [
    ['meta', { name: 'theme-color', content: '#3eaf7c' }],
    ['meta', { name: 'og:type', content: 'website' }],
    ['link', { rel: 'icon', href: '/favicon.ico' }]
  ],
  
  // Markdown配置
  markdown: {
    lineNumbers: true,
    math: true,  // 数学公式支持
    image: {
      lazyLoading: true
    }
  },
  
  // 主题配置
  themeConfig: {
    // 站点Logo
    logo: '/logo.svg',
    siteTitle: '我的文档站',
    
    // 导航栏
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' },
      { text: 'API参考', link: '/api/' },
      {
        text: '更多',
        items: [
          { text: 'GitHub', link: 'https://github.com/user/repo' },
          { text: '更新日志', link: '/changelog' }
        ]
      }
    ],
    
    // 侧边栏配置
    sidebar: {
      '/guide/': [
        {
          text: '开始',
          collapsed: false,
          items: [
            { text: '介绍', link: '/guide/' },
            { text: '快速开始', link: '/guide/getting-started' },
            { text: '配置', link: '/guide/configuration' }
          ]
        },
        {
          text: '进阶',
          collapsed: false,
          items: [
            { text: '自定义主题', link: '/guide/custom-theme' },
            { text: '部署', link: '/guide/deployment' }
          ]
        }
      ],
      '/api/': [
        {
          text: 'API参考',
          items: [
            { text: '概览', link: '/api/' },
            { text: '配置选项', link: '/api/config' },
            { text: 'Frontmatter', link: '/api/frontmatter' }
          ]
        }
      ]
    },
    
    // 社交链接
    socialLinks: [
      { icon: 'github', link: 'https://github.com/user/repo' }
    ],
    
    // 页脚
    footer: {
      message: '基于 MIT 许可发布',
      copyright: 'Copyright © 2024-present 作者'
    },
    
    // 搜索配置
    search: {
      provider: 'local',
      options: {
        translations: {
          button: {
            buttonText: '搜索文档',
            buttonAriaLabel: '搜索文档'
          },
          modal: {
            noResultsText: '无法找到相关结果',
            resetButtonTitle: '清除查询条件',
            footer: {
              selectText: '选择',
              navigateText: '切换'
            }
          }
        }
      }
    },
    
    // 大纲配置
    outline: {
      level: [2, 3],
      label: '页面导航'
    },
    
    // 文档页脚
    docFooter: {
      prev: '上一页',
      next: '下一页'
    },
    
    // 编辑链接
    editLink: {
      pattern: 'https://github.com/user/repo/edit/main/docs/:path',
      text: '在GitHub上编辑此页'
    },
    
    // 最后更新时间
    lastUpdated: {
      text: '最后更新于',
      formatOptions: {
        dateStyle: 'short',
        timeStyle: 'short'
      }
    }
  }
})

部署脚本

package.json配置

{
  "name": "my-docs",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "docs:dev": "vitepress dev",
    "docs:build": "vitepress build",
    "docs:preview": "vitepress preview"
  },
  "devDependencies": {
    "vitepress": "^1.5.0"
  }
}

Cloudflare Pages构建命令详解

自定义构建脚本（可选）

#!/bin/bash
# build.sh - 自定义构建脚本

set -e

echo "🔍 检查Node版本..."
node -v

echo "📦 安装依赖..."
npm ci

echo "🔨 构建文档..."
npm run docs:build

echo "✅ 构建完成！"
ls -la docs/.vitepress/dist

常见问题解决

构建错误处理

问题1：Node版本不兼容

Error: Node.js version 16.x is not supported

解决方案：在Cloudflare Pages设置中指定Node版本

• Settings → Environment variables
• 添加 NODE_VERSION = 20

问题2：依赖安装失败

npm ERR! ERESOLVE unable to resolve dependency tree

解决方案：更新package.json添加覆盖配置

{
  "overrides": {
    "vite": "^5.0.0"
  }
}

问题3：路由404错误

Page not found: /guide/getting-started

解决方案：

1. 确认文件名正确（getting-started.md）
2. 检查 cleanUrls 配置
3. 验证侧边栏链接路径

问题4：Hydration Mismatch

[Vue warn]: Hydration node mismatch

解决方案：

• 禁用Cloudflare Pages的HTML “Auto Minify”功能
• Speed → Optimization → Auto Minify → 取消勾选HTML

性能优化建议

1. 图片优化

// 使用内置图片懒加载
markdown: {
  image: { lazyLoading: true }
}

2. 代码分割 VitePress默认已优化，无需额外配置。

3. 缓存策略

// 启用构建缓存
export default {
  cacheDir: '.vitepress/cache'
}

4. 大型站点优化

// 对于1000+页面的站点
export default {
  // 启用MPA模式（禁用SPA）
  // 适合超大型文档站点
  // vite: { ssr: { noExternal: true } }
}

5. 搜索优化

search: {
  provider: 'local',
  options: {
    // 限制搜索结果数量
    miniSearch: {
      searchOptions: {
        fuzzy: 0.2,
        prefix: true,
        boost: { title: 4, text: 2, titles: 1 }
      }
    }
  }
}

参考资料

• VitePress部署文档 - 官方部署指南
• Cloudflare Pages VitePress指南 - Cloudflare官方教程
• VitePress配置参考 - 完整配置API
• VitePress主题配置 - 默认主题配置选项