使用 Wrangler CLI 部署 VitePress 到 Cloudflare Pages 教程

本教程适用于在 Windows 平台 下本地开发 VitePress 项目的用户，详细说明如何使用 Wrangler CLI 工具将静态网站部署到 Cloudflare Pages，并涵盖两种情况：

• 尚未创建 Cloudflare Pages 项目
• 已创建 Cloudflare Pages 项目

准备工作

1. 安装 Node.js
2. 安装 Wrangler CLI：

npm install -g wrangler

3. 登录 Cloudflare 账号：

wrangler login

情况一：尚未创建 Cloudflare Pages 项目

1. 运行命令创建项目：

wrangler pages project create your-project

2. 根据提示输入：
   • 项目名称（建议唯一）
   • 是否使用构建命令（选择否即可）
   • 输出目录（VitePress 默认是 docs/.vitepress/dist）

情况二：已经创建 Cloudflare Pages 项目

假设你已经在 Cloudflare Pages 创建了项目名为 your-project（请将 your-project 替换为实际项目名），可以直接进行部署。

1. 配置 package.json

{
  "scripts": {
    "docs:build": "vitepress build docs",
    "deploy": "npm run docs:build && wrangler pages deploy docs/.vitepress/dist --project-name=your-project --branch=main"
  }
}

2. 执行一键部署

在终端中运行：

npm run deploy

重要说明：关于部署分支（branch）

Cloudflare Pages 支持多个部署环境，每次部署时会生成唯一子域名（如 abc123.your-project.pages.dev），但只有 --branch=main 才会更新主环境 your-project.pages.dev。

因此，建议始终添加 --branch=main，否则你的正式访问地址不会自动更新！

可选：Windows 批处理部署脚本

在项目根目录创建一个 deploy.bat 文件：

@echo off
echo [1/3] 构建 VitePress 项目...
call npm run docs:build

echo [2/3] 部署到 Cloudflare Pages 主环境...
wrangler pages deploy docs\.vitepress\dist --project-name=your-project --branch=main

echo [3/3] 部署完成！
pause

部署结果说明

• your-project.pages.dev：主环境部署成功后，正式对外访问的网址
• 随机哈希子域名：每次部署自动生成，用于预览
• 绑定自定义域名：你可以将如 example.org 指向主环境

自定义域名绑定说明（使用 CNAME 记录）

若你希望绑定自己的域名（如 example.org），请在你的 DNS 服务商控制台添加以下解析记录：

类型：CNAME
主机记录：@（或 www，具体视你绑定方式而定）
目标值：your-project.pages.dev

添加后，回到 Cloudflare Pages 项目的“自定义域名”设置中验证并启用 HTTPS 即可。

通过本教程配置后，你可以一键构建并发布你的 VitePress 文档站点到 Cloudflare Pages，非常适合独立开发者和团队协作。