从零搭建这个博客：Hexo + Fluid + Cloudflare Pages 全流程踩坑记录

前言

如果你也想搭一个「写起来不折腾、访问不卡顿」的个人技术博客，你可以参考参考我的文章。

我会给你一个完整的部署流程，还会附带我踩到的坑之类的。开始之前你得先准备好以下环境：Node.js、git，还有一个github账号（gitlab也可以）

用到这些技术：

  • 静态博客框架：Hexo 8.x
  • 主题：hexo-theme-fluid（中文友好，Material Design 风格）
  • 部署平台：Cloudflare Pages（国内直连比 GitHub Pages 快 5-10 倍）
  • 源码仓库：任意源码仓库
  • 线上地址：https://msty2003-blogs.pages.dev 也就是本博客的地址

一、本地初始化 Hexo

环境前提：

  • Node.js ≥ 18（建议 20 LTS）
  • Git
  • 一个顺手的终端（PowerShell / Git Bash / zsh 都行）
1
2
3
4
5
6
7
8
9
10
11
12
# 1. 全局装 hexo-cli
npm install -g hexo-cli

# 2. 初始化博客目录（myblogs 是目录名，可改）
hexo init myblogs
cd myblogs

# 3. 安装依赖
npm install

# 4. 本地预览，浏览器打开 http://localhost:4000
hexo server

如果 hexo init 之后 hexo server 能正常打开 Hello World 默认页，说明本地环境通了。

问题 1：hexo init 静默退出

我第一次跑 hexo init myblogs 时，命令看起来「成功」了（没报错、退出码 0），但 source/_posts/ 是空的。原因是网络问题导致 hexo 在拉模板时静默失败。

解决：删掉重来，或者 hexo init myblogs --no-install 完手动 npm install。

二、配置 _config.yml

myblogs/_config.yml 是整个博客的中枢。我把关键字段列出来：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 站点信息
title: MSTY · 技术笔记
subtitle: 记录踩过的坑与走通的路
description: 一个 Java / Python / 前端开发者的个人技术博客
keywords: Hexo, Fluid, Java, Python, Minecraft Mod, 前端
author: MSTY
language: zh-CN
timezone: Asia/Shanghai

# URL（部署到 Cloudflare Pages 后填这个）
url: https://msty2003-blogs.pages.dev
permalink: :year/:month/:day/:title/

# 主题
theme: fluid

# 部署
deploy:
  type: git
  repo: git@github.com:MSTY2003/myblogs-source.git
  branch: main

问题 2：YAML 合并注释把 deploy 块污染了

我在文件里看到 deploy: 下面混进了一段 # repo: ... 的注释，导致 Hexo 解析时把整段 deploy 当成空对象。hexo deploy 静默退出，不报错也不工作。这段内容其实是我一开始照抄网上教程的时候直接复制导致的，没换行…

解决：删掉那段 ## Docs: ... 的示例代码，只保留真实的 repo 和 branch。

三、换主题：landscape → Fluid

landscape 是 Hexo 默认主题，UI 太朴素。Fluid 是中文社区里口碑最好的一款也是我个人看起来风格比较满意的一款：

1
npm install --save hexo-theme-fluid

然后把 _config.yml 里的 theme: landscape 改成 theme: fluid。

接下来是重要的一步——从 node_modules 里把主题默认配置复制出来，做成可编辑副本：

1
2
3
# PowerShell
Copy-Item node_modules/hexo-theme-fluid/_config.yml _config.fluid.yml
# 或者手动移动出来也可以，这段是我让ai执行的
1
2
# Git Bash / Linux
cp node_modules/hexo-theme-fluid/_config.yml _config.fluid.yml

问题 3：中文路径 + PowerShell 路径解析

Copy-Item 在 PowerShell 里遇到中文/带空格的路径经常翻车。如果失败，直接用绝对路径：

1
Copy-Item "$PWD\node_modules\hexo-theme-fluid\_config.yml" "$PWD\_config.fluid.yml"

_config.fluid.yml 是 Fluid 主题的「覆盖层」，Hexo 加载时会用它覆盖 node_modules/hexo-theme-fluid/_config.yml 的默认值。永远不要直接改 node_modules 里的文件——npm install 一升级就被覆盖了。

四、部署到 GitHub Pages（可选，但推荐先走一遍）

这一步只是为了让你在互联网上先看到你的博客「真的能跑起来」。如果你希望直接到国内能访问的环节推荐跳过这步，直接走第五章的 Cloudflare Pages——国内访问快很多。

  1. GitHub 上建一个 repo：MSTY2003.github.io（用户名一致会自动启用 Pages）
  2. 配 SSH key（一次性，本地git执行）：
    1
    2
    3
    ssh-keygen -t ed25519 -C "your_email@example.com"
    # 把 ~/.ssh/id_ed25519.pub 内容粘到 GitHub Settings → SSH and GPG keys
    ssh -T git@github.com  # 测试连通
  3. 改 _config.yml 里的 deploy.repo 为 git@github.com:MSTY2003/MSTY2003.github.io.git
  4. 装部署插件并推送：
    1
    2
    3
    npm install --save hexo-deployer-git
    hexo clean
    hexo deploy

问题 4：Permission denied (publickey)

八成是 SSH key 没配，或者配了但 ~/.ssh/config 没指认。我当时的解决：

1
2
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

部署成功 1-2 分钟后访问 https://MSTY2003.github.io 就能看到博客。

问题 5：GitHub Pages 缓存不更新

有时候 hexo deploy 成功但页面没变。强刷：Ctrl + Shift + R（Windows/Linux）/ Cmd + Shift + R（Mac）。

五、迁移到 Cloudflare Pages（国内访问提速）

GitHub Pages 在国内直连经常 5-30 秒甚至超时。Cloudflare Pages 免费、有全球 CDN、国内走 Cloudflare 合作线路，速度快很多。

5.1 关键认知：CF Pages 要源码，不要 build 产物

这是最容易踩的坑：

  • ❌ 错误做法：把 hexo generate 生成的 public/ 目录推上去
  • ✅ 正确做法：把整个源码仓库（含 package.json）推上去，让 CF 在云端跑 hexo generate

所以我建了第二个仓库 MSTY2003/myblogs-source（私有），专门存源码。_config.yml 里的 deploy.repo 改到这个仓库。

5.2 Cloudflare 控制台绑定

  1. 登录 https://dash.cloudflare.com/
  2. 左侧 Workers & Pages → Create → Pages 标签
  3. 选 Connect to Git → 选 MSTY2003/myblogs-source
  4. Build 配置：
    • Framework preset: Hexo
    • Build command: npm run build（即 hexo generate）
    • Build output directory: public
    • Root directory: 留空

5.3 推送后第一次构建失败的排查

问题 6：YN0028: The lockfile would have been modified by this install, which is explicitly forbidden

CF 默认包管理器是 yarn，但我同时有 package-lock.json 和 yarn.lock。yarn 看到 lockfile 跟当前 node_modules 不一致就不让装。

解决：让 CF 用 npm，方法是让仓库里只有 package-lock.json：

1
2
3
4
5
git rm --cached yarn.lock
echo "yarn.lock" >> .gitignore
git add .gitignore
git commit -m "remove yarn.lock, force npm"
git push

CF 重新构建就能过了。

构建成功后，访问 https://<project-name>.pages.dev 就能看到博客——而且国内访问比 GitHub Pages 快很多。

六、.gitignore 模板

不要把 node_modules 和 public/ 推上去：

1
2
3
4
5
6
7
8
9
10
.DS_Store
Thumbs.db
db.json
*.log
node_modules/
public/
.deploy*/
.deploy_git/
.hexo/
yarn.lock

.deploy_git/ 是 hexo deploy 生成的中间产物，CF 不需要。

七、VS Code 任务一键发布

把下面保存为 .vscode/tasks.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "📝 新建文章",
      "type": "shell",
      "command": "hexo new",
      "args": ["${input:postTitle}"],
      "problemMatcher": []
    },
    {
      "label": "🚀 部署博客",
      "type": "shell",
      "command": "npm",
      "args": ["run", "pub"],
      "problemMatcher": []
    },
    {
      "label": "👀 本地预览",
      "type": "shell",
      "command": "npm",
      "args": ["run", "prew"],
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "postTitle",
      "type": "promptString",
      "description": "文章标题",
      "default": "my-new-post"
    }
  ]
}

package.json 加两个 script：

1
2
3
4
"scripts": {
  "pub": "hexo clean && hexo deploy --generate",
  "prew": "hexo server"
}

之后写文章的流程是：

  1. Ctrl+Shift+P → Tasks: Run Task → 📝 新建文章 → 输入标题
  2. 在 source/_posts/<标题>.md 里写
  3. 🚀 部署博客 一键推送，CF 自动构建上线

八、写完后回到首页的效果

部署完打开 https://msty2003-blogs.pages.dev，你应该看到：

  • 顶部 banner 区域有打字机效果滚动字幕
  • 中间是文章卡片列表（默认 10 篇/页）
  • 底部导航：首页 / 归档 / 分类 / 标签 / 关于 / 搜索 / 关灯
  • 暗色模式开关（关灯按钮）

_config.fluid.yml 里可以微调：

  • banner.subtitle — banner 滚动字幕
  • banner.img — banner 背景图（留空有默认纯色）
  • navbar — 顶部导航
  • footer — 页脚社交链接
  • color — 主题色（默认蓝紫）

九、这套方案适合谁

  • ✅ 想写技术博客、折腾成本要低
  • ✅ 文章数量较少（Hexo 纯静态生成，文章多了每次部署会变慢）
  • ✅ 在意国内访问速度

附录：常用命令速查

目的 命令
新建文章 hexo new "标题"
新建草稿 hexo new draft "标题"
本地预览 hexo server / npm run prew
生成静态文件 hexo generate
部署 hexo deploy / npm run pub
清理缓存 hexo clean
一键发布 npm run pub（clean + generate + deploy）

下一步计划：加 Giscus 评论系统 + Algolia 搜索 + 自定义 about 页。下一篇写《用 Giscus 给 Hexo 博客加评论》。到时候我再给我的博客加上评论区的功能。

教程
#Hexo #Fluid #Cloudflare Pages #GitHub Pages #踩坑记录
从零搭建这个博客：Hexo + Fluid + Cloudflare Pages 全流程踩坑记录
https://msty2003-blogs.pages.dev/2026/07/09/build-blog-from-scratch/
作者
MSTY
发布于
2026年7月9日
许可协议