05 · 部署（Cloudflare Pages）

把博客推到全球 CDN，拿到一个能给朋友的链接。全程免费、不需要服务器、不需要域名、不需要备案、国内外都能访问。

一、为什么选 Cloudflare Pages

简短回答

国内可访问 + 完全免费 + 自动构建 + 自动 HTTPS——四个条件同时满足的最佳方案。

选型对比

平台	国内访问	自动构建	备案	备注
Cloudflare Pages ⭐	✅	✅	❌	单选最佳
Vercel	⚠️ 需 VPN	✅	❌	国际线路好，但国内体验差
Netlify	⚠️ 较慢	✅	❌	体验中等
GitHub Pages	⚠️ 慢/不稳	✅	❌	国内体验差
~~Gitee Pages 免费版~~	-	-	-	2024 已停
Gitee Pages Pro	✅ 最快	-	✅ 需要	付费 + 备案
阿里云 OSS / EdgeOne	✅ 最快	自己写	✅ 需要	付费 + 备案 + 配置复杂

💡 不推荐双部署：之前做过 Cloudflare + Vercel 双部署，但发现心智成本高于实际收益——两个平台都要监控构建状态、两套域名要同步说明。单 Cloudflare 已经覆盖国内国外，没必要再加一层。

二、前置：代码必须在 GitHub

Cloudflare Pages 通过连接 Git 仓库自动构建。它支持 GitHub / GitLab，不支持 Gitee —— 所以一定要先把代码推到 GitHub（参考 03-git-and-remote.md）。

Gitee 镜像可保可不保——保留的话仓库链接给国内朋友看代码会快一些；不保的话也没问题。

三、关键配置：vercel.json

⚠️ 这个文件叫 vercel.json 是 Vercel 的命名习惯，但和我们用 Cloudflare Pages 不冲突。Cloudflare 不读这个文件——它的构建配置在网页上设置。
保留这个文件的好处：
万一以后想试试 Vercel，不用重新写
文件本身解释了"build 命令"和"输出目录"，对后来者友好

仓库根目录：

json

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "buildCommand": "npm run build",
  "outputDirectory": ".vitepress/dist",
  "installCommand": "npm install",
  "framework": null,
  "cleanUrls": true,
  "trailingSlash": false
}

每个字段的意义：

字段	作用
`buildCommand`	构建命令
`outputDirectory`	VitePress 输出在 `.vitepress/dist`，不是 `dist`
`installCommand`	依赖安装
`cleanUrls: true`	让 `/foo` 自动映射到 `foo.html`
`trailingSlash: false`	不强制末尾斜杠

四、Cloudflare Pages 部署流程

Step 1：注册 Cloudflare

https://dash.cloudflare.com/sign-up

填邮箱 + 密码即可，不需要信用卡，不需要域名。

Step 2：进入 Pages

侧边栏 Workers & Pages → 顶部 tab Pages → Create a project → Connect to Git

Step 3：连接 GitHub

授权 Cloudflare 访问 GitHub，选择你的博客仓库。

第一次会跳到 GitHub 让你勾选哪些仓库给 Cloudflare 访问。建议选 "Only select repositories" 只授权当前博客仓库（最小权限原则）。

Step 4：构建配置

字段	值
Project name	`<你的项目名>`（决定子域名 `<name>.pages.dev`）
Production branch	`main`
Framework preset	`VitePress`（如果有）或 `None`
Build command	`npm run build`
Build output directory	`.vitepress/dist`
Root directory	（留空）
Environment variables	加 `NODE_VERSION` = `20`（保险起见）

⚠️ Cloudflare 默认 Node 版本可能太老（v18），最好显式指定 NODE_VERSION=20 或更高。否则可能构建失败或 VitePress 警告。

Step 5：Save and Deploy

等 1-2 分钟构建完成，拿到链接：

https://<project>.pages.dev

这就是你要给朋友的链接。

五、自动构建工作流

你 push 到 GitHub main 分支
        ↓
Cloudflare 监听到（10 秒内）
        ↓
拉代码 + npm install + npm run build
        ↓
推到全球 CDN
        ↓
博客更新（30 秒 - 2 分钟）

完全自动化——你不需要再去 Cloudflare 网页点任何按钮。

写新内容并发布

bash

cd ~/notes/我的主题

# 1. 写新内容（编辑 .md 文件）
# ...

# 2. 提交
git add . && git commit -m "feat: 新文章 - XXX"

# 3. 推送
git push

# 4. 30 秒后博客自动更新

六、常见错误

错误 1：Build Failed - No Output Directory

原因：构建配置里 Build output directory 写错（默认是 public 或 dist）。

修复：必须写成 .vitepress/dist。

错误 2：构建报 Node 版本警告

原因：Cloudflare 默认 Node 版本不够新。

修复：环境变量加 NODE_VERSION=20。

错误 3：直接访问子页面 404

现象：从首页跳转能进 /guide/intro 没问题，但复制 URL 在新窗口打开就 404。

原因：VitePress 的 cleanUrls: true 让链接没 .html 后缀，但默认服务器不知道要加。

修复：项目设置 → Settings → Pages → 启用 Always Use HTTPS 和 cleanUrls 兼容（Cloudflare Pages 默认就支持，多数情况下不需要操作）。如果仍 404，可在 _redirects 文件里手动配置（详见 Cloudflare 文档）。

错误 4：中文 URL 在分享时变得很丑

现象：复制 /游戏复盘 到微信变成 /%E6%B8%B8%E6%88%8F%E5%A4%8D%E7%9B%98。

修复：用 VitePress 的 rewrites 把中文文件名映射到英文 URL（参见 04-vitepress.md "URL 设计"）。

七、域名相关

Cloudflare Pages 子域名

域名	何时变化
`<project>.pages.dev`	永不变（指向最新生产部署）
`<branch>.<project>.pages.dev`	跟随分支
`<commit>.<project>.pages.dev`	每次部署都新生成

分享给朋友只用第一个。

自定义域名（可选，~50 元/年）

如果想要 blog.mqd.dev 这种：

买域名（推荐 Cloudflare Registrar —— 域名按成本价卖，没溢价；或 Porkbun）
Cloudflare Pages 项目 Custom domains → Set up a domain → 加你的域名
Cloudflare 自动签 HTTPS

💡 域名买在 Cloudflare 的好处：自动绑 DNS、零配置——没什么仪式感但最省事。
域名不需要备案——Cloudflare 服务器在海外。

八、Cloudflare Pages 免费版的限制

资源	免费额度	个人博客够用吗
请求数	无限（!!!）	✅ 远远够
自定义域名数	100 / 项目	✅ 够
构建次数	500 次 / 月	✅ 够
项目数量	100 个	✅ 够
商用	✅ 允许	个人博客也允许商用

💡 Cloudflare Pages 比 Vercel 慷慨——Vercel 限制带宽（100GB/月），Cloudflare 不限制请求数。

九、备选方案

备选 1：Vercel

如果你的博客主要给国外朋友看，或者你恰好有 VPN 习惯，Vercel 也是优秀方案。配置流程几乎一样：

vercel.com/new → Import → 选你的 GitHub 仓库
Framework Preset 选 VitePress
Deploy

⚠️ Vercel 默认开 Deployment Protection（401 Auth），需要去 Settings → Deployment Protection → 关闭 Vercel Authentication。

备选 2：迁到国内（更高性能）

如果博客流量真的大、国内访问要极致快，可以考虑：

腾讯云 EdgeOne Pages：支持 GitHub mirror，部分免费额度
阿里云 OSS + 自配 CDN：自由度最高，配置最复杂
Gitee Pages Pro：原生支持 Gitee 仓库，但要付费 + 备案

这些方案都需要国内域名备案，不适合"想快速上线"的场景。

下一步

部署完成 → 06-toolchain.md 把流程工具化。

05 · 部署（Cloudflare Pages） ​

一、为什么选 Cloudflare Pages ​

简短回答 ​

选型对比 ​

二、前置：代码必须在 GitHub ​

三、关键配置：vercel.json ​

四、Cloudflare Pages 部署流程 ​

Step 1：注册 Cloudflare ​

Step 2：进入 Pages ​

Step 3：连接 GitHub ​

Step 4：构建配置 ​

Step 5：Save and Deploy ​

五、自动构建工作流 ​

写新内容并发布 ​

六、常见错误 ​

错误 1：Build Failed - No Output Directory ​

错误 2：构建报 Node 版本警告 ​

错误 3：直接访问子页面 404 ​

错误 4：中文 URL 在分享时变得很丑 ​

七、域名相关 ​

Cloudflare Pages 子域名 ​

自定义域名（可选，~50 元/年） ​

八、Cloudflare Pages 免费版的限制 ​

九、备选方案 ​

备选 1：Vercel ​

备选 2：迁到国内（更高性能） ​

下一步 ​

💬 评论与建议