记录一次 Hexo + Cloudflare Pages 的踩坑经历

梦幻泡影2025-12-162025-12-16

这篇文章算是一篇踩坑记录。

我在部署 Hexo 博客时，参考的是博主 cmliussss 的这篇教程：
https://blog.cmliussss.com/p/HexoBlogNo1/

教程本身没有问题，我也能看出来它在当时是完全可用的。但在我实际操作时，却在 Cloudflare Pages 部署阶段卡住了，而且错误信息一开始并不直观。

折腾了一圈之后，发现问题出在一个教程里完全没提到、但现在却是必须存在的文件：wrangler.jsonc。

下面按时间顺序记录一下我整个排查和解决的过程。

一、问题是怎么出现的

前面的步骤都很顺：

Hexo 初始化
主题配置
本地构建

本地 public/ 目录正常生成，浏览也没问题。

于是我照着教程，把项目推到 Git，然后去 Cloudflare Pages：

新建 Pages 项目
关联 Git 仓库
选择默认构建配置

结果在 Deploy 阶段直接失败。

二、Cloudflare Pages 的报错信息

构建日志里能看到类似这样的内容（不同账号可能略有差异）：

No wrangler configuration file found

或者直接提示：

缺少 wrangler.json / wrangler.jsonc

这一步其实挺迷惑的：

我只是部署一个 纯静态 Hexo 博客
没用 Workers
没用 KV / D1

为什么会突然要求 Wrangler 配置？

三、最开始的误判

我一开始以为是：

构建命令写错了
输出目录不对
Node 版本不兼容

于是我：

反复改 Build command
改 Build output directory
查了一圈 Hexo + Pages 的老教程

结果发现一个共同点：
老教程里，几乎都没有 wrangler.jsonc 这个文件

这时候才意识到：
很可能是 Cloudflare Pages 自身的行为变了。

四、真正的原因：Cloudflare 更新了 Pages 构建逻辑

继续翻 Cloudflare 的新文档和一些近期 issue 后，结论基本明确了：

Pages 的构建流程现在已经深度统一到 Wrangler
即使你不用 Workers
构建阶段也会尝试读取 Wrangler 配置文件

如果仓库根目录：

没有 wrangler.json
也没有 wrangler.jsonc

那就会 直接失败。

而老教程写的时候，这一步是不存在的。

五、解决方案其实很简单

既然 Pages 只是需要一个 Wrangler 配置文件，那最简单的办法就是：
在项目根目录补一个最小可用的 wrangler.jsonc

不需要任何 Workers 配置，只要能让 Pages 知道：

就够了。

六、我实际使用的 wrangler.jsonc

在 Hexo 项目的source目录新建一个最小配置的 wrangler.jsonc 文件，内容仅需指定输出目录即可。

这个文件加上之后，我什么都没再改，直接重新部署就成功了。

{
  "name": "hexo-blog",  // 必须和 Cloudflare 项目名称完全一致！
  "compatibility_date": "2025-12-13",
  "assets": {
    "directory": "./",  // 因为你的静态文件（index.html、css、js 等）直接在仓库根目录
    "not_found_handling": "single-page-application"  // 推荐：支持博客的干净 URL（如 /2025/12/13/hello-world/ 自动返回 index.html）
  }
}