坑二：Gitee Pages 下架#

网上教程清一色教你”仓库 → 服务 → Gitee Pages → 启动”，但 2025 年 10 月 11 日这个功能已经下架（官方 issue #ID1EVM 确认）。

替代方案实测

坑三：Hexo 改完主题没生效#

Hexo 有缓存。改完配置必须：

1
hexo clean && hexo generate && hexo server

少了 clean，一半的改动都不会生效。

坑四：换主题迁移（Hexo → Firefly）#

用 Hexo + Butterfly 跑了三天，还是换成了 Firefly（Astro 主题）。迁移本身不难，但有三个坑：

1. Node 版本要够

Firefly 要求 Node ≥ 22.23，本机的 22.22 差一个小版本。engines 字段默认只警告不拦截，构建照样能过，但遇到诡异报错先核对版本再排查。

2. pnpm 是硬依赖

Firefly 用 pnpm 管依赖，package.json 里有 preinstall: npx only-allow pnpm，用 npm 装会被直接拒绝。更坑的是本机的 corepack 坏了（路径拼接错乱），最后绕过 pnpm 直接用 node_modules/.bin 里的本地二进制跑构建链。

3. front-matter 字段名不一样

字段名写错不会报错，文章会直接”消失”——因为校验不过被丢弃了。迁移后先看文章总数对不对。

心得#

遇到问题先看报错信息本身，它通常已经把原因说清楚了。别急着搜，先读懂。

先说结论#

方案三件套：

为什么是Twikoo#

我的博客托管在Cloudflare Pages上，纯静态，没地方存评论。加评论系统必然要引入一个常年在线的后端加一个数据库，所以选型其实是在选”后端跑在哪”。

候选挨个过一遍：

• giscus：评论者必须用GitHub账号登录。我的读者是同学和朋友，基本没有GitHub账号，评论区会变成摆设。淘汰。
• waline：功能最全，但后端免费托管的位置全撞墙。Vercel默认域名大陆基本连不上，也没有Cloudflare Workers官方适配。淘汰。
• 腾讯云CloudBase：国内速度天花板，但免费体验版无法在HTTP网关里配置跨域域名，这一步绕不过去；个人版19.9元/月起。学生党暂时退场。
• HuggingFace：以前是免费方案里的明星，2026年7月起免费账号已经不能创建Docker Space，要PRO月付9美元。这条路刚被堵死。
• Cloudflare Workers：官方适配+D1免费数据库+我正好有CF账号，差点就成了。卡在域名上：部署后的地址是twikoo.xxx.workers.dev，这个后缀在大陆被DNS污染，直接超时。没有自定义域名就没法用。
• EdgeOne Makers：必须绑定自定义域名，默认域名链接只有3小时有效期。

最后剩Netlify：Twikoo官方部署文档里评级四星，免费方案里最高。免费额度每月12.5万次请求、100小时函数时长，大陆访问速度在免费平台里算好的。

架构一句话#

Twikoo负责接收和审核评论，Netlify负责让它跑起来，MongoDB Atlas负责存。前端JS从CDN加载，评论数据走后端进数据库。

部署过程#

1
git clone --depth 1 https://github.com/twikoojs/twikoo-netlify.git
2
cd twikoo-netlify
3
npm install

1
[build]
2
  functions = "netlify/functions"
3

4
[functions]
5
  node_bundler = "esbuild"

1
netlify env:set MONGODB_URI "mongodb+srv://用户:密码@cluster0.xxxx.mongodb.net/?retryWrites=true&w=majority"
2
netlify env:set NODE_VERSION "24"
3
netlify deploy --prod --dir . --functions netlify/functions

坑一：整个站点401#

部署完打开，等来的不是”运行正常”，是Netlify的登录跳转页。所有路径全部401，连首页都是。查API看站点状态，claimed是true，一度以为是令牌权限问题。

真实原因：新账号的站点可见性。进Netlify控制台 → Site configuration → Access and security → Site visibility，改成Public，立刻恢复。

顺带一提，注册后的验证邮件最好第一时间点掉，新账号功能受限有一半是因为邮箱没验证。

坑二：504 Inactivity Timeout#

登录墙解决了，再打开变成504，函数被调用但一直挂起直到超时，函数日志里一片空白。

这次排了好一会儿。后来顺着调用链想：函数启动后第一件事就是连数据库。回Atlas控制台一看，Network Access里只有一条记录，我自己的IP。而Netlify服务器的出口IP每次都不一样，永远进不了白名单。

解决：Network Access → ADD IP ADDRESS → Allow access from anywhere（0.0.0.0/0）。

有人会担心安全。M0免费库有独立的数据库用户名密码，白名单只是第一道门，个人博客的流量级这么用是社区标准做法。

坑三：手改连接串改出双斜杠#

Atlas复制的连接串自带<db_password>占位符，替换密码时手一抖，主机名前多打了一个斜杠，变成mongodb+srv://user:pass@//cluster0...，驱动直接报错。建议整串复制，只动占位符那一段。

顺便科普：DNS污染#

为什么你的pages.dev博客能打开，workers.dev就不行？DNS污染指的是国内查询某些域名的IP时会得到一个假答案，于是永远连不上。pages.dev这个后缀没被污染，workers.dev被污染了。同属Cloudflare，两种命运。这也是选型里”有没有自定义域名”变成关键变量的原因。

最后花了多少钱#

唯一的”付费”是一个多小时。个人博客的流量级，这些额度根本用不完。

还可以继续做的#

• 管理员密码要在评论区后台手动设一次，评论的删除和禁用词都在那里管
• 邮件通知可选配Resend免费API，Netlify环境发邮件走HTTP通道
• 以后买了自定义域名，可以把整套迁到速度更快的平台上，Twikoo支持评论数据导出导入，搬家不丢数据

技术栈#

刚开张时用的是 Hexo + Butterfly，用了三天就换成了 Firefly，完整过程写在了搭建实录里。

一个重要的教训#

网上的教程有很强的时效性。我照着 2021 年的文章操作，卡在了”开启 Gitee Pages 服务”这一步——这个功能 2025 年 10 月已经下架了。

搜索结果里的答案往往互相矛盾，最靠谱的做法是直接查官方文档或官方 issue。

接下来要做的#

• 本地跑通 Hexo，部署到 Cloudflare Pages
• 换上 Firefly 主题（Astro）
• 绑定自己的域名
• 持续更新内容

慢慢来，先把内容写好。

前置参数（Front-matter）#

每篇文章开头的 --- 包裹区域叫 front-matter，用来声明元信息：

1
---
2
title: 文章标题
3
published: 2026-10-19
4
description: 一句话简介（显示在列表卡片里）
5
image: ./images/cover.png
6
tags: [标签1, 标签2]
7
category: 分类
8
pinned: false    # 设为 true 置顶
9
---

常用语法#

1
[链接文字](https://example.com)
2
![图片说明](./images/photo.jpg)

1
function greet(name) {
2
  console.log(`Hello, ${name}!`);
3
}

主题扩展语法#

Firefly 在标准 Markdown 之上加了一些好用的指令：

1
> [!NOTE]
2
> 提示内容
3

4
> [!WARNING]
5
> 警告内容

1
::github{repo="CuteLeaf/Firefly"}

发布#

写完保存，双击 发布.bat，构建完成后自动上传到 Cloudflare Pages。