部署指南

本指南将帮助你将 VitePress 博客部署到 Vercel 或 Cloudflare Pages。

📋 前置要求

• Node.js 18+
• npm 或 yarn
• GitHub 账号
• Vercel 或 Cloudflare 账号

🚀 部署到 Vercel

方法一：通过 Vercel Dashboard

1. 推送代码到 GitHub

   git init
   git add .
   git commit -m "Initial commit"
   git remote add origin <your-github-repo-url>
   git push -u origin main

2. 在 Vercel 导入项目

   • 访问 Vercel
   • 点击 "Add New..." → "Project"
   • 导入你的 GitHub 仓库
   • Vercel 会自动检测 VitePress 配置

3. 配置构建设置（如果需要）

   • Framework Preset: VitePress
   • Build Command: npm run build
   • Output Directory: docs/.vitepress/dist
   • Install Command: npm install

4. 部署

   • 点击 "Deploy"
   • 等待构建完成
   • 访问提供的 URL

方法二：使用 Vercel CLI

# 安装 Vercel CLI
npm i -g vercel

# 登录
vercel login

# 部署
vercel

# 生产环境部署
vercel --prod

☁️ 部署到 Cloudflare Pages

方法一：通过 Cloudflare Dashboard

1. 推送代码到 GitHub（同上）

2. 在 Cloudflare Pages 创建项目

   • 访问 Cloudflare Dashboard
   • 进入 "Pages" → "Create a project"
   • 选择 "Connect to Git"
   • 选择你的 GitHub 仓库

3. 配置构建设置

   • Framework preset: None（或选择 Vite）
   • Build command: npm run build
   • Build output directory: docs/.vitepress/dist
   • Root directory: /（项目根目录）

4. 环境变量（可选）

   • 如果需要，可以添加环境变量

5. 部署

   • 点击 "Save and Deploy"
   • 等待构建完成
   • 访问提供的 URL

方法二：使用 GitHub Actions（已配置）

项目已包含 GitHub Actions 工作流文件 .github/workflows/deploy-cloudflare.yml。

设置步骤：

1. 获取 Cloudflare API Token

   • 访问 Cloudflare API Tokens
   • 点击 "Create Token"
   • 使用 "Edit Cloudflare Workers" 模板
   • 或创建自定义 token，需要以下权限：
     • Account: Cloudflare Pages:Edit
     • Zone: Zone:Read

2. 获取 Account ID

   • 在 Cloudflare Dashboard 右侧边栏找到 Account ID

3. 在 GitHub 设置 Secrets

   • 进入仓库 Settings → Secrets and variables → Actions
   • 添加以下 secrets：
     • CLOUDFLARE_API_TOKEN: 你的 API Token
     • CLOUDFLARE_ACCOUNT_ID: 你的 Account ID

4. 推送代码

   git push origin main

   • GitHub Actions 会自动触发部署

🔧 本地开发

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览构建结果
npm run preview

📝 注意事项

1. 图片路径: 确保 markdown 文件中的图片路径使用相对路径（如 pic/image.png），VitePress 会自动处理。

2. Base URL: 如果部署到子路径（如 https://example.com/blog/），需要修改 .vitepress/config.mts 中的 base 配置：

   base: '/blog/'

3. 自定义域名:

   • Vercel: 在项目设置中添加自定义域名
   • Cloudflare Pages: 在 Pages 项目设置中添加自定义域名

4. 404 页面: VitePress 会自动生成 404 页面，你也可以在 docs/404.md 中自定义。

🐛 常见问题

构建失败

• 检查 Node.js 版本（需要 18+）
• 确保所有依赖都已安装
• 检查 markdown 文件语法

图片不显示

• 确保图片路径使用相对路径
• 检查图片文件是否已提交到仓库
• 确保图片路径大小写正确

路由 404

• 检查侧边栏配置中的链接路径
• 确保 markdown 文件路径与配置一致
• 检查 base 配置是否正确

📚 更多资源

• VitePress 文档
• Vercel 文档
• Cloudflare Pages 文档