Hexo+CloudflarePages建站与踩坑教程

写在开始之前

今年寒假，我在 B 站刷视频看到了使用 Cloudflare Pages 建站的内容，沉寂已久的建站之魂再次燃烧，折腾了一圈踩了不少坑，也就有了这篇保姆级教程。

为什么选 Cloudflare Pages

相比于其他静态站点托管平台，Cloudflare Pages 的优势非常突出：

• 几乎零成本：平台本身完全免费，无流量上限、无构建次数限制，你只需要承担域名费用即可

• 全球加速：自带 Cloudflare 全球 CDN 节点，国内访问速度也相对可观

• 自动部署：绑定 GitHub 仓库后，推送代码自动触发构建部署，无需手动操作

• 免费 SSL：自动签发并续期 HTTPS 证书，不用自己折腾证书配置

• 功能丰富：支持自定义域名、缓存规则、重定向、边缘函数等进阶能力

准备工作

开始之前请确保你具备以下条件：

1. 一台可以联网的电脑（本文以 Windows 11 为例，Mac/Linux 操作逻辑一致）

2. 已安装 Git 和 Node.js（版本要求见下文踩坑说明）

3. 一个可用的邮箱，以及支付宝 / Visa / 万事达卡（用于购买域名）

4. 一个 GitHub 账号（用于托管代码和自动构建）

5. 一个 Cloudflare 账号（用于托管域名和部署站点）

6. 一个域名注册商账号（可选，文中以 Spaceship 为例，也可用阿里云、Namecheap 等）

💡 版本提示：Hexo 7.x 建议 Node.js 14.0+，Hexo 8.x 建议 Node.js 20.19+，建议优先选择 LTS 版本。

正式开始

1. 注册 Cloudflare 账号

1. 打开 cloudflare.com，点击右上角 Log in

2. 在登录页下方点击 Sign up，填写邮箱和密码，完成注册

3. 登录邮箱查收验证邮件，点击验证链接激活账号

4. 进入个人控制台后，点击右上角人像图标 → 选择 Language → 找到简体中文切换界面语言，方便后续操作

2. 购买域名

域名注册商可以自由选择，国内推荐阿里云、腾讯云，国外推荐 Spaceship、Namecheap、Cloudflare Registrar。这里以 Spaceship 为例演示。

域名选择建议

购买步骤

1. 进入 spaceship.com，在中间搜索框输入你想要的域名，查询是否可注册

2. 选好心仪的域名后，点击 Add to cart 加入购物车

3. 点击右上角购物车图标，进入结算页面

4. 根据提示注册账号，填写联系人信息，添加付款方式并完成支付

5. 支付成功后，域名会出现在你的域名管理列表中

3. 托管域名到 Cloudflare

把域名的 DNS 解析交给 Cloudflare 管理，是使用 Pages 服务的前提。

1. 回到 Cloudflare 控制台，左侧边栏选择 域 → 点击 加入域

2. 在输入框中填写你购买的根域名（例如 example.com，不要加 www. 前缀），点击继续

3. 计划选择页面，选择最下方的 Free 免费套餐，点击继续

4. 进入 DNS 记录检查页面：

5. 确认记录后，点击继续前往激活

6. 此时页面会显示 Cloudflare 分配给你的两个名称服务器（Nameserver），格式类似：

   1 2	erin.ns.cloudflare.com roan.ns.cloudflare.com

   先不要关闭这个页面。

去域名注册商修改 Nameserver

1. 打开 Spaceship 官网，点击右上角 Launchpad → 选择 Domain Manager

2. 找到你的域名，点击进入管理页面

3. 侧边栏选择 Nameservers & DNS → 点击 Change

4. 选择 Custom nameservers，把刚才 Cloudflare 给出的两个 Nameserver 地址依次粘贴进去

5. 点击 Save nameserver settings 保存

验证生效

1. 回到 Cloudflare 页面，点击我已更新名称服务器 → 点击立即检查名称服务器

2. 点击 Back to domains，等待域名状态变为活动

   ⚠️ Nameserver 生效不是即时的，快则十几分钟，慢则 24~48 小时，耐心等待即可。

3. 域名激活后，点击域名进入管理页 → 右侧选择 DNS 记录，可以后续在这里添加解析记录。

4. 准备 GitHub 仓库

Cloudflare Pages 通过拉取 GitHub 仓库代码来构建站点，我们需要先把 Hexo 项目托管上去。

方式一：使用模板快速创建（适合新手）

1. 打开 GitHub 模板仓库：https://github.com/kratos-rebirth/quickstart

2. 点击 Use this template → 选择 Create a new repository

3. 填写仓库名称，Visibility 选择 Private（私有仓库，别人看不到源码）

4. 点击 Create repository，等待模板复制完成

5. 进入你创建的仓库，点击 Code 按钮，复制仓库地址

6. 在本地项目文件夹打开终端，执行克隆命令：

   1	git clone <你的仓库地址>

7. 私有仓库会弹出身份验证，按提示完成 GitHub 登录授权即可。

方式二：本地初始化 Hexo 项目再推送（推荐）

如果你想从零搭建自己的 Hexo 项目，推荐这种方式：

1. 本地安装 Hexo 命令行工具：

   1	npm install -g hexo-cli

2. 初始化博客项目：

   1 2 3

   hexo init my-blog cd my-blog npm install

3. 本地预览确认正常：

   1	hexo server

   浏览器访问 http://localhost:4000，能看到默认博客页面即为成功。

4. 初始化 Git 仓库并推送到 GitHub：

   1 2 3 4 5 6

   git init git add . git commit -m "init hexo blog" git branch -M main git remote add origin <你的仓库地址> git push -u origin main

5. 创建 Cloudflare Pages 应用

1. 回到 Cloudflare 控制台，点击左侧 Compute → Workers 和 Pages

2. 点击创建应用程序 → 选择页面下方的 想要部署 Pages？ → 点击开始使用

3. 选择连接到 Git，登录你的 GitHub 账号，授权 Cloudflare 访问你的博客仓库

4. 选择你的博客仓库，点击开始设置

构建设置（最容易出错的环节）

在 “设置构建和部署” 页面，按以下填写：

• 生产分支：一般填 main（根据你的仓库默认分支而定）

• 构建命令：

1

npm install && hexo clean && hexo generate

1

git submodule update --init --recursive && npm install && hexo clean && hexo generate

• 构建输出目录：public（Hexo 生成的静态文件默认都在 public 文件夹）

配置环境变量（必做，否则大概率构建失败）

点击环境变量 → 添加变量：

• 变量名：NODE_VERSION

• 值：20（根据你的 Hexo 版本选择对应的 Node LTS 版本）

💡 这是 90% 新手踩坑的点：Cloudflare 默认 Node 版本可能很低，和新版 Hexo 不兼容，导致构建直接报错。

全部设置好后，点击保存并部署，等待第一次构建完成。

6. 绑定自定义域名

构建成功后，你会得到一个 *.pages.dev 的默认域名，但我们一般用自己的域名。

1. 进入 Workers 和 Pages 页面，点击你刚创建的 Pages 应用

2. 顶部选择 自定义域 → 点击设置自定义域

3. 输入你的根域名（如 example.com），点击继续 → 点击激活域

4. 重复上述步骤，再添加一个 www 前缀的域名（如 www.example.com）

配置完成后，访问你的域名，就能看到你的 Hexo 博客了。

常见踩坑与问题排查

这部分是整篇教程的精华，都是我实际踩过或者见过高频出现的问题。

1. 构建失败怎么办？

点击 Pages 应用 → 构建 → 点击失败的构建号 → 查看构建日志，根据报错排查：

• hexo: command not found：没安装依赖，检查构建命令是否有 npm install

• Node 版本相关报错：检查环境变量 NODE_VERSION 是否配置正确

• 主题文件缺失：样式全乱、页面报错，基本是子模块没拉取，构建命令加上子模块更新

• ERR! ENOENT：路径错误，检查构建输出目录是不是 public

• 权限报错：私有仓库授权过期，重新连接 GitHub 账号授权

2. 网站打开样式丢失 / 404

• 检查 _config.yml 中的 url 和 root 配置：

  • 根域名部署：url: https://你的域名.com，root: /

  • 子目录部署：url: https://你的域名.com/blog，root: /blog/

• 执行 hexo clean && hexo g 本地生成看 public 文件夹是否正常

• 清一下浏览器缓存和 Cloudflare 缓存再试

3. 域名访问不生效

• 刚修改完 Nameserver 请耐心等待，最长 48 小时生效

• 可以用 nslookup 你的域名 命令查看解析是否指向 Cloudflare

• 检查 Pages 里自定义域状态是否为 “有效”

• 确认 SSL/TLS 加密模式设为灵活或严格，不要设为 “关闭”

4. 提交代码后不自动更新

• 检查 GitHub 仓库是否推送成功，分支是否和构建分支一致

• 去 Cloudflare Pages 看有没有新的构建任务

• 如果构建成功但内容没更新，去 Cloudflare 缓存 → 清除所有内容，清缓存后刷新页面

5. 图片不显示

• 确认 _config.yml 中 post_asset_folder: true 已开启

• 检查图片路径写法是否正确，建议用相对路径或绝对路径

• 确认图片文件已经提交到 GitHub 仓库

进阶优化

1. 配置缓存规则

在 Cloudflare 缓存规则里添加规则，对静态资源（图片、CSS、JS）设置较长缓存时间，提升访问速度。

2. 配置重定向

可以设置 www 域名 301 重定向到根域名，或者 http 自动跳转到 https，统一域名权重。

3. 开启压缩

在 速度 → 优化 里开启 Brotli 压缩，减小文件体积，加快加载速度。

4. 配置 404 页面

Hexo 根目录 source 文件夹下放一个 404.html，Cloudflare Pages 会自动识别。

5. 访问统计

可以接入 Cloudflare 自带的 Web Analytics，免费且无广告，查看访问量、访客地区等数据。

结尾

通过以上步骤，你就可以搭建起一个稳定、高速且完全免费的 Hexo 个人博客了。后续关于 Hexo 的主题配置、插件安装、SEO 优化等内容，我会陆续更新。

如果这篇文章对你有帮助，欢迎分享给更多有需要的朋友。