Saul的个人博客

搭建实录：从零到上线踩过的坑

Wed, 14 Oct 2026 00:00:00 GMT

坑一：Git 代理导致 clone 失败#

现象

Terminal window

1
git clone https://gitee.com/xxx/yyy.git
2
fatal: unable to access '...': Failed to connect to gitee.com:443
3
over proxy 127.0.0.1 after 2036 ms

定位

代理残留在了 Git 全局配置里，但本地那个端口根本没服务在跑：

Terminal window

1
git config --global --get https.proxy
2
# http://127.0.0.1:10808
3

4
netstat -ano | grep 10808
5
# 无输出 = 端口没有监听

解决

Terminal window

1
git config --global --unset http.proxy
2
git config --global --unset https.proxy

坑二：Gitee Pages 下架#

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

替代方案实测

平台	结果	原因
Gitee Pages	不可用	服务已下架
腾讯云 EdgeOne	不可用	国内加速区域默认域名仅 3 小时有效，直连 401
Vercel	不可用	中国 IP 新账号触发风控，人工审核周期不可控
Cloudflare Pages	可用	免费、免备案，`xxx.pages.dev` 永久公开

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

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

Terminal window

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 字段名不一样

Hexo	Firefly	说明
`date`	`published`	发布日期
`categories`（数组）	`category`（单个字符串）	只能填一个分类
`cover`	`image`	封面图
`sticky`	`pinned: true`	置顶

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

心得#

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

零成本给博客加评论系统：Twikoo+Netlify+MongoDB实录

Mon, 19 Oct 2026 00:00:00 GMT

博客上线没几天，评论区还空着。这篇记录我给博客加评论系统的全过程，总花费0元，总耗时一个多小时，其中大半时间在排错。三个坑一个比一个隐蔽，写下来给后来的人省时间。

先说结论#

方案三件套：

角色	选了什么	花费
评论后端程序	Twikoo 2.0.15	开源免费
后端托管	Netlify Functions	免费层
数据库	MongoDB Atlas M0	免费层

为什么是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. 注册两个账号#

Netlify：邮箱注册，验证邮箱，然后在User settings → Applications里生成一个Personal access token。

MongoDB Atlas：邮箱注册，建集群时选M0 FREE（永久免费层，512MB存储），Region选东京（离国内近）。过程中要建一个数据库用户，密码自己设好记牢；网络访问后面会讲到，这里先埋个伏笔。

2. 部署后端#

官方模板是配合GitHub fork用的，我用Netlify命令行从本地直接推，连fork都省了：

Terminal window

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

在根目录建一个netlify.toml：

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

4
[functions]
5
  node_bundler = "esbuild"

设置环境变量后一条命令部署：

Terminal window

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

打开分配的地址，看到”Twikoo 云函数运行正常”就算成功。

一个容易漏的点：Netlify的envId必须带上/.netlify/functions/twikoo后缀，跟Vercel那种直接给域名的不一样。博客前端配置envId时少了这段后缀，请求会404。

坑一：整个站点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，两种命运。这也是选型里”有没有自定义域名”变成关键变量的原因。

最后花了多少钱#

项目	费用
Twikoo	0（开源）
Netlify Functions	0（每月12.5万次请求额度）
MongoDB Atlas M0	0（512MB永久免费层）

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

还可以继续做的#

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

你好，世界：我的博客开张了

Fri, 16 Oct 2026 00:00:00 GMT

缘起#

折腾了一个下午，终于把这个博客搭起来了。

过程比想象中顺利，也比想象中坑多。趁热把踩过的坑记下来，免得以后忘了。

技术栈#

环节	选型	说明
静态站点生成器	Astro 7	构建 fast，默认零 JS，Markdown/MDX 写作
主题	Firefly	基于 Fuwari 二开的中文友好主题，颜值在线
代码托管	Gitee	国内访问快
部署	Cloudflare Pages	全球 CDN，免备案

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

一个重要的教训#

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

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

接下来要做的#

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

慢慢来，先把内容写好。

Markdown 写作指南：语法速查

Thu, 15 Oct 2026 00:00:00 GMT

新建文章#

双击项目根目录的 新建文章.bat，输入英文文件名后会自动生成模板并用编辑器打开。

文章都在 firefly/src/content/posts/ 目录下，图片放同级的 images/ 文件夹。

前置参数（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
---

字段	必填	说明
`title`	是	显示用的标题，可写中文
`published`	是	发布日期
`description`	建议	摘要，列表页显示
`image`	建议	封面图，相对路径 `./images/xxx.jpg`
`tags`	否	数组写法 `[A, B]`
`category`	否	只能填一个
`pinned`	否	`true` 置顶

常用语法#

标题#

# 到 ###### 对应一到六级标题。

强调#

粗体、斜体、删除线。

列表#

无序列表用 -，有序列表用 1.。

链接与图片#

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

代码块#

用三个反引号包裹，并在开头标注语言：

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

引用#

这是一段引用文字。

表格#

语法	效果
`文字`	粗体
`文字`	斜体

主题扩展语法#

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

提醒框（Callout）#

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

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

支持 NOTE / TIP / IMPORTANT / WARNING / CAUTION。

GitHub 卡片#

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

CuteLeaf

Firefly

🍀Firefly, fresh and aesthetic Astro blog theme template.

—

MIT

Astro

发布#

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