使用 Cloudflare Pages + GitHub 免费部署 VuePress 2 博客完全指南
记录从零到一搭建 VuePress 2 博客并免费部署到 Cloudflare Pages 的完整流程。
前言
VuePress 2 是一个基于 Vue 3 的静态网站生成器，适合用于构建文档站、博客和个人网站。Cloudflare Pages 提供免费的静态站点托管，配合 GitHub 可以实现自动化部署。
本指南将带你完成：
- ✅ 创建 GitHub 仓库并配置 Personal Access Token
- ✅ 注册 Cloudflare 账号
- ✅ 安装 Wrangler CLI 并登录
- ✅ 创建和配置 VuePress 2 项目
- ✅ 编写一键部署脚本
- ✅ 解决常见问题（SSL 错误、域名变更等）
目录
环境要求
- Node.js 16+（推荐 18 或 20）
- Git（用于版本管理，可选但推荐）
- GitHub 账号
- Cloudflare 账号（免费）
第一步：GitHub 准备
1. 创建新仓库
- 访问 https://github.com/new
- 填写仓库信息：
- Repository name:
vuepress-site（或其他你喜欢的名字） - Description: 可选
- Public（公开）或 Private（私有）
- Repository name:
- 不要勾选 "Initialize this repository with a README"
- 点击 "Create repository"
📸 截图位置：创建成功后会显示仓库地址，如
https://github.com/你的用户名/vuepress-site
2. 生成 Personal Access Token（可选但推荐）
如果你需要通过命令行推送代码，需要生成 Token：
- 访问 https://github.com/settings/tokens
- 点击 "Generate new token" → "Fine-grained tokens"
- 配置：
- Token name:
vuepress-deploy - Expiration: 无期限或 90 天
- Repository access: 选择上面的仓库
- Permissions:
- ✅ Contents: Read & write
- ✅ Metadata: Read-only
- Token name:
- 点击 "Generate token"
- 复制并保存好 Token（只显示一次）
⚠️ 注意：Token 相当于密码，不要泄露！后续部署脚本会用到。
第二步：Cloudflare 准备
1. 注册 Cloudflare 账号
- 访问 https://dash.cloudflare.com/sign-up
- 用邮箱注册（如 your-email@example.com）
- 验证邮箱
- 登录控制台
2. 安装 Wrangler CLI（命令行工具）
npm install -g wrangler
验证安装：
wrangler --version
# 应该显示类似：wrangler 4.x.x
💡 提示：Wrangler 是 Cloudflare 的命令行工具，用于管理 Pages、Workers 等。
3. 登录 Cloudflare
wrangler login
运行后会自动打开浏览器，登录你的 Cloudflare 账号并授权。
成功后，命令行会显示：
👋 You are logged in with an OAuth Token, associated with email xxx@xx.com
📸 截图：授权页面会显示权限范围，包括
pages:write等。
第三步：创建 VuePress 项目
1. 创建项目目录
mkdir vuepress-site
cd vuepress-site
npm init -y
2. 安装 VuePress 2 及相关依赖
npm install -D vuepress@next @vuepress/bundler-vite@next @vuepress/theme-default@next sass-embedded
版本说明：
vuepress@next- VuePress 2（当前是 RC 版本）@vuepress/bundler-vite@next- Vite 打包器@vuepress/theme-default@next- 默认主题sass-embedded- 样式预处理器（默认主题需要）
3. 创建目录结构
mkdir -p docs/.vuepress
mkdir docs/guide
目录结构：
vuepress-site/
├── docs/
│ ├── .vuepress/
│ │ └── config.js
│ ├── README.md
│ └── guide/
│ └── README.md
├── package.json
└── node_modules/
4. 配置文件
创建 docs/.vuepress/config.js：
import { defineUserConfig } from 'vuepress'
import { defaultTheme } from '@vuepress/theme-default'
import { viteBundler } from '@vuepress/bundler-vite'
export default defineUserConfig({
lang: 'zh-CN',
title: '我的网站',
description: '使用 VuePress 2 构建的网站',
bundler: viteBundler(),
theme: defaultTheme({
navbar: [
{
text: '首页',
link: '/'
},
{
text: '指南',
link: '/guide/'
}
]
})
})
5. 创建页面内容
首页 docs/README.md：
---
home: true
title: 首页
heroText: 欢迎来到我的网站
tagline: 使用 VuePress 2 构建
---
## 开始使用
这是一个使用 VuePress 2 默认主题构建的网站。
### 快速链接
- [指南](/guide/)
- [GitHub](https://github.com)
指南页 docs/guide/README.md：
# 指南
这是指南页面的内容。
## 基本用法
VuePress 2 是一个静态网站生成器，基于 Vue.js。
## 更多信息
访问 [VuePress 官方文档](https://v2.vuepress.vuejs.org/) 了解更多。
第四步：配置项目
1. package.json 脚本
确保 package.json 包含这些脚本：
{
"name": "vuepress-site",
"version": "1.0.0",
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs",
"preview": "vuepress preview docs"
},
"devDependencies": {
"vuepress": "^2.0.0-rc.0",
"@vuepress/bundler-vite": "^2.0.0-rc.0",
"@vuepress/theme-default": "^2.0.0-rc.0",
"sass-embedded": "^1.98.0"
}
}
2. 构建测试
npm run build
成功后会生成 docs/.vuepress/dist/ 目录，包含 index.html、guide/index.html 等。
本地预览：
npm run preview
访问 http://localhost:8080
3. 创建 .gitignore
echo "node_modules/
.vuepress/dist/
.DS_Store
*.log
.env
.env.local
" > .gitignore
第五步：一键部署脚本
1. 创建 deploy.bat（Windows）
在项目根目录创建 deploy.bat：
@echo off
chcp 65001 >nul
title VuePress 一键部署
color 0A
echo ==========================================
echo VuePress 2 一键部署脚本
echo ==========================================
echo.
cd /d "%~dp0"
:: 检查是否已登录
echo [1/4] 检查 Cloudflare 登录状态...
wrangler whoami >nul 2>&1
if errorlevel 1 (
echo ❌ 未检测到登录状态
echo.
echo 请先运行以下命令登录:
echo wrangler login
echo.
pause
exit /b 1
)
echo ✅ 已登录
echo.
:: 构建网站
echo [2/4] 安装依赖 (如果需要)...
if not exist "node_modules\package.json" (
echo 正在安装依赖...
call npm install
if errorlevel 1 (
echo ❌ 依赖安装失败
pause
exit /b 1
)
echo ✅ 依赖安装完成
) else (
echo ✅ 依赖已存在，跳过
)
echo.
echo [3/4] 构建网站...
call npm run build
if errorlevel 1 (
echo ❌ 构建失败，请检查错误信息
pause
exit /b 1
)
echo ✅ 构建完成
:: 部署
echo.
echo [4/4] 部署到 Cloudflare Pages...
echo.
wrangler pages deploy docs/.vuepress/dist --project-name vuepress-site --commit-dirty=true
if errorlevel 1 (
echo.
echo ❌ 部署失败
echo 可能原因:
echo - 网络连接问题
echo - 项目不存在
echo - 权限不足
echo.
pause
exit /b 1
)
echo.
echo ==========================================
echo ✅ 部署成功！
echo ==========================================
echo.
echo 📍 你的网站地址将在 5-10 秒生效
echo.
echo 提示:
echo - 更新内容后，重新运行此脚本即可部署
echo - 首次访问可能需要等待 CDN 缓存
echo.
pause
⚠️ 注意：
--project-name需要替换成你的 Cloudflare Pages 项目名（在控制台查看）。
2. 创建 deploy.sh（macOS/Linux）
#!/bin/bash
echo "=========================================="
echo "VuePress 2 一键部署脚本"
echo "=========================================="
echo ""
# 检查登录
if ! wrangler whoami > /dev/null 2>&1; then
echo "❌ 未检测到登录状态"
echo "请先运行: wrangler login"
exit 1
fi
echo "✅ 已登录"
# 安装依赖
if [ ! -d "node_modules" ]; then
echo "[1/3] 安装依赖..."
npm install || exit 1
fi
# 构建
echo "[2/3] 构建网站..."
npm run build || exit 1
# 部署
echo "[3/3] 部署到 Cloudflare Pages..."
wrangler pages deploy docs/.vuepress/dist --project-name vuepress-site
if [ $? -eq 0 ]; then
echo ""
echo "✅ 部署成功！"
echo ""
echo "网站地址将在 5-10 秒生效"
else
echo "❌ 部署失败"
exit 1
fi
给执行权限：
chmod +x deploy.sh
3. 创建 wrangler.toml（可选）
name = "vuepress-site"
compatibility_date = "2024-01-01"
[pages]
pages_build_output_dir = "docs/.vuepress/dist"
[build]
command = "npm run build"
[build.environment]
NODE_VERSION = "18"
第六步：首次部署
步骤 1：登录 Cloudflare（如果还未登录）
wrangler login
浏览器会打开，登录并授权。
步骤 2：创建 Cloudflare Pages 项目
方法 A：使用 Wrangler 创建（推荐）
wrangler pages project create vuepress-site --production-branch main
会提示你选择连接方式，选择 "Upload folder" 或 "Git" 都可以。
方法 B：在网页上创建
- 访问 https://pages.cloudflare.com/
- 点击 "Create a project"
- 选择 "Upload assets" 或 "Connect to Git"
- 按提示操作
步骤 3：首次部署
运行脚本：
deploy.bat # Windows
# 或
./deploy.sh # macOS/Linux
脚本会自动：
- 检查依赖（第一次会 npm install）
- 运行
npm run build - 上传到 Cloudflare Pages
成功后会显示：
✨ Deployment complete! Take a peek over at https://xxx.vuepress-site.pages.dev
那个链接就是你的网站地址！
常见问题
Q1: 部署后域名一直在变？
原因：每次用 wrangler pages deploy 没有 --project-name 或者创建了新项目。
解决：
- 删除多余的 Cloudflare Pages 项目（在控制台）
- 确保
wrangler pages deploy加上--project-name 你的项目名 - 以后只用这一个项目，域名固定（
xxx.vuepress-site.pages.dev）
Q2: 访问出现 ERR_SSL_VERSION_OR_CIPHER_MISMATCH
原因：新站点的 SSL 证书还没激活。
解决：
- 等待 5-10 分钟再访问
- 或者在 Cloudflare 控制台里查看项目状态是否为 "Active"
Q3: wrangler 报错 "Must specify a directory"
原因：没有正确指定构建输出目录。
解决：
wrangler pages deploy docs/.vuepress/dist --project-name vuepress-site
或者在 wrangler.toml 中配置 pages_build_output_dir。
Q4: 想要绑定自定义域名？
- 在 Cloudflare Pages 项目设置 → "Custom domains"
- 添加你的域名（如
blog.yourdomain.com） - 按提示在域名 DNS 处添加 CNAME 记录
- Cloudflare 会自动配置 SSL
Q5: 更新内容后如何重新部署？
直接运行 deploy.bat 或 ./deploy.sh 即可。
总结
完整流程回顾
- ✅ GitHub 创建仓库 → 获取 Token（可选）
- ✅ Cloudflare 注册 → 安装 Wrangler → 登录
- ✅ 创建 VuePress 2 项目 → 安装依赖 → 配置
- ✅ 编写
deploy.bat一键脚本 - ✅ 首次运行脚本，完成部署
- ✅ 获得访问链接：
https://xxx.vuepress-site.pages.dev
文件清单
vuepress-site/
├── deploy.bat # 一键部署脚本（Windows）
├── deploy.sh # 一键部署脚本（macOS/Linux）
├── wrangler.toml # Wrangler 配置（可选）
├── docs/
│ ├── .vuepress/
│ │ └── config.js # VuePress 配置
│ ├── README.md # 首页
│ └── guide/
│ └── README.md # 指南页
├── package.json
├── .gitignore
└── node_modules/
后续维护
- 添加新页面：在
docs/下创建.md文件 - 修改导航：编辑
docs/.vuepress/config.js的navbar - 更新内容：运行
deploy.bat重新部署 - 查看日志：Wrangler 输出或 Cloudflare Pages 控制台
后记
这套方案的优势：
- ✅ 完全免费：GitHub + Cloudflare 都不花钱
- ✅ 自动化：写完代码一键部署
- ✅ 快速：全球 CDN，访问速度快
- ✅ 稳定：Cloudflare 背靠大树
适合用于：
- 个人博客
- 技术文档
- 项目主页
- 学习笔记
希望这篇指南能帮助你顺利搭建自己的网站！🚀
记录日期：2025-03-20
作者：基于实际操作整理