基于 Fluid 的高可用 Hexo 博客实践

本文最后更新于 2025年12月25日 凌晨

谨以此文纪念本站的诞生。
本站架构遵循计算与存储分离原则：基于 Hexo + Fluid 构建静态资源，源码托管于 GitHub，利用 Cloudflare Pages 与 Vercel 实现多线路全球分发。

1. 核心架构设计

在开始动工前，明确本博客的工程拓扑：

  • 核心仓库 (hexo-blog): 仅包含站点配置 (_config.yml)、文章源码 (source/) 和依赖描述 (package.json)。
  • 主题管理 (Submodule): 将 Fluid 主题作为子模块引入，确保主题更新与个性化配置解耦。
  • 部署策略 (Edge Computing): 放弃传统的 GitHub Pages 直连，利用 Cloudflare 的 Anycast 网络实现毫秒级加载。

2. 环境初始化

基础依赖

请确保本地开发环境（Windows/Mac/Linux）已安装以下工具链：

  • Git: 版本控制核心。
  • Node.js: 建议安装 LTS 版本 (推荐 v18+)。
  • Hexo CLI:
    1
    npm install -g hexo-cli

仓库构建

本博客在本地建立项目 Devhub/hexo-blog。为了保持仓库整洁，不直接 clone 整个主题代码，而是采用初始化生成：

1
2
3
4
# 初始化脚手架
hexo init hexo-blog
cd hexo-blog
npm install

此时目录结构应清晰如下：

1
2
3
4
5
6
7
8
9
10
11
12
.
├── _config.landscape.yml
├── _config.yml      # 站点全局配置
├── package.json     # 依赖管理
├── scaffolds        # 模板文件
│   ├── draft.md
│   ├── page.md
│   └── post.md
├── source           # 博客文章与自定义资源
│   └── _posts
│       └── hello-world.md
└── themes           # 主题目录

Git 策略提示 建议在 .gitignore 中排除 node_modules 和 public 目录。package-lock.json 建议保留以锁定依赖版本，确保多端构建一致性，但如果你追求极致的仓库轻量化，确保 package.json 版本号写死即可。

3. 主题管理：Fluid 的非侵入式集成

为了解决“直接下载主题包难以更新”和“修改源码导致冲突”的痛点，我们采用 Git Submodule 方案。

安装主题

1
2
3
4
5
# 移除默认主题（可选）
rm -rf themes/landscape

# 将 Fluid 挂载为子模块
git submodule add https://github.com/fluid-dev/hexo-theme-fluid.git themes/fluid

配置解耦 (Shadow Config)

Fluid 支持“影子配置”模式。我们将主题的配置文件复制到根目录，并重命名为 _config.fluid.yml。Hexo 会优先读取此文件，从而覆盖 themes/fluid/_config.yml 中的默认值。

1
cp themes/fluid/_config.yml _config.fluid.yml

之后所有对主题的修改（导航栏、颜色、功能开关）均在根目录的 _config.fluid.yml 中进行，永远不要修改 themes/fluid 目录下的文件。

站点基础配置

修改 hexo-blog/_config.yml：

1
2
3
4
5
6
7
# Extensions
theme: fluid
language: zh-CN
timezone: Asia/Shanghai

# URL (Cloudflare Pages 提供的域名或自定义域名)
url: https://codebearjourney.top

4. 深度定制与美化

Mac-Style 代码高亮

Fluid 支持自定义 CSS 注入。为了实现类似 Mac 窗口的圆角与红绿灯效果，我们采用外部注入的方式。

  1. 配置 Highlight.js： 在 _config.fluid.yml 中设置：
1
2
3
4
5
6
7
8
9
10
11
12
# 实现高亮的库，对应下面的设置
# Highlight library
# Options: highlightjs | prismjs
lib: "highlightjs"

highlightjs:
  # 在链接中挑选 style 填入
  # Select a style in the link
  # See: https://highlightjs.org/demo/
  style: "atom-one-dark"
  style_dark: "atom-one-dark"
  bg_color: true
  1. 创建样式文件： 新建 source/css/mac.styl，粘贴以下内容：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
.highlight
    background: #282C34   /* Atom One Dark 背景色 */
    border-radius: 5px
    box-shadow: 0 10px 30px 0 rgba(0, 0, 0, .4)
    padding-top: 30px

    &::before
      content: ' '
      position: absolute
      top: 15px
      left: 15px
      width: 12px
      height: 12px
      border-radius: 50%
      background: #fc625d
      box-shadow: 20px 0 #fdbc40, 40px 0 #35cd4b
  1. 注入配置： 在 _config.fluid.yml 中注册：
1
2
custom_css:
  - /css/mac.css

注意：虽然源文件是 stylus，Hexo 会自动编译为 css，此处引用需写 .css 后缀。

数学公式渲染 (LaTeX)

为了在技术文章中优雅地展示公式，使用 hexo-math。

安装hexo-math插件:

1
2
3
# 使用 npm 安装 Hexo-math插件
## Docs: https://github.com/hexojs/hexo-math
npm install hexo-math --save

在站点 _config.yml 中添加：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Hexo-math
## Docs: https://github.com/hexojs/hexo-math
math:
  katex:
    css: 'https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.css'
    options:
      throwOnError: false
  mathjax:
    css: 'https://cdn.jsdelivr.net/npm/hexo-math@4.0.0/dist/style.css'
    options:
      conversion:
        display: false
      tex:
      svg:

优化建议：默认对所有页面关闭公式渲染（提升加载速度），仅在需要的文章 Front-matter 中开启(参见后文 Front-matter 部分)

5. 内容生产流

Front-matter 模板工程化

修改 scaffolds/post.md，预设常用的元数据，减少重复劳动：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
---
title: {{ title }}
date: {{ date }}
updated:
index_img:
category_bar: true
categories:
  - Foo
  - Bar
tags:
  - Foo
  - Bar
katex: false
mathjax: false
excerpt: ''
sticky: 
---

静态资源压缩

在构建流水线中加入压缩环节，减少传输体积。

1
2
3
# 使用 npm 安装 hexo-all-minifier 插件
## Docs: https://github.com/chenzhutian/hexo-all-minifier
npm install hexo-all-minifier --save

在 _config.yml 开启:

1
2
3
# All in one. Minifier & Optimization plugin for Hexo.
## Docs: https://github.com/chenzhutian/hexo-all-minifier
all_minifier: true

6. 高可用部署架构

本站采用 双线热备 方案。GitHub 仅作为代码仓库，由 Cloudflare Pages 和 Vercel 负责分发。

graph LR
    User(用户访问) --> DNS{Cloudflare DNS}
    DNS -- "线路优选 (默认)" --> CF[Cloudflare Pages]
    DNS -- "故障切换 (备用)" --> Vercel[Vercel]
    CF -- "自动拉取" --> GH[(GitHub Repo)]
    Vercel -- "自动拉取" --> GH

6.1 部署到 GitHub Pages (基础)

这是最经典的部署方式，通过 Git 钩子将生成的静态文件推送到 GitHub 仓库。哪怕后续使用 CDN 加速，保留原始的 GitHub Pages 也是极好的“源站”备份。

  1. 创建仓库： 在 GitHub 上创建一个名为 tianyuxbear.github.io 的公开仓库。
  2. 安装部署插件：
1
2
# 使用 npm 安装 Github Deploy插件
npm install hexo-deployer-git --save
  1. 配置站点文件： 修改 _config.yml 中的部署模块：
1
2
3
4
5
6
# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git
  repo: git@github.com:tianyuxbear/tianyuxbear.github.io.git
  branch: master
  1. 一键部署： 执行以下组合命令，完成清除缓存、生成静态文件、推送部署：
1
hexo clean && hexo g && hexo d

6.2 部署至 Cloudflare Pages (核心)

相比 GitHub Pages，Cloudflare 提供国内更友好的 CDN 节点和 HTTP/3 支持。

  1. 绑定仓库： 在 Cloudflare Dashboard 中关联 GitHub 账号，选择 hexo-blog 仓库。
  2. 构建配置：
    • Build Command: 空
    • Build Output Directory: 空(默认是/)
  3. 等待部署： 点击部署，几分钟后即可通过 https://tianyuxbear-github-io.pages.dev/ 访问。

6.3 部署至 Vercel (灾备)

配置逻辑同上。Vercel 的国内访问速度在部分地区可能优于 Cloudflare，可作为互补。

  • Framework Preset: Other。
  • Output Directory: /。

部署成功后，即可通过 https://tianyuxbear-github-io.vercel.app/ 访问。

6.4 自定义域名配置 (重要)

为了获得最佳的访问速度和 HTTPS 支持，我们采用 DNS 托管模式 将域名完全接入 Cloudflare。

第一步：域名注册 (以阿里云为例)

  1. 在阿里云官网购买域名（如 codebearjourney.top）。
  2. 完成实名认证。

第二步：DNS 迁移至 Cloudflare 这是加速的关键步骤。将域名的 DNS 解析权交给 Cloudflare，利用其全球 Anycast 网络。

  1. 登录 Cloudflare Dashboard，点击 “Add a Site”，输入你的域名。
  2. 选择 “Free” 计划。
  3. Cloudflare 会扫描当前的 DNS 记录，确认无误后点击 Continue。
  4. 修改 Nameservers：
    • Cloudflare 会提供两个 Nameserver 地址（如 bob.ns.cloudflare.com 等）。
    • 回到阿里云域名控制台 -> 域名列表 -> 管理 -> DNS 修改 -> 修改 DNS 服务器。
    • 将阿里云默认的 DNS 修改为 Cloudflare 提供的这两个地址。
  5. 等待生效（通常在 10 分钟到 24 小时内）。

第三步：绑定 Pages

  1. 在 Cloudflare Pages 项目页面，点击 “Custom domains”。
  2. 输入 codebearjourney.top。
  3. 由于你的 DNS 已经托管在 Cloudflare，系统会自动添加 CNAME 记录并申请 SSL 证书。
  4. (可选) 同时添加 www.codebearjourney.top 并设置重定向，符合用户习惯。

通过此配置，访问请求路径为： 用户 -> Cloudflare 边缘节点 (DNS+CDN) -> Pages 静态资源。

7. SEO 与收录优化

为了让 Google 和 Bing 快速索引，我们需要配置 Sitemap 并完成站长验证。

7.1 生成 Sitemap

告诉搜索引擎你的网站结构和文章路径。

1
2
# 使用 npm 安装 Hexo-sitemap 插件
npm install hexo-generator-sitemap --save

在 _config.yml 确认开启：

1
2
3
# 确保 sitemap 插件已启用
sitemap:
  path: sitemap.xml

7.2 站长平台验证 (DNS 方式)

传统的验证方式是上传一个 HTML 文件到 public 目录，这会污染源码且容易在重构中丢失。强烈推荐使用 Cloudflare DNS 进行 TXT 记录验证，这种方式无代码侵入，且得益于 Cloudflare 的生效速度，通常秒级通过。

Google Search Console

  1. 获取验证码：
    • 登录 Google Search Console。
    • 在左上角选择资源类型时，选择 “网域” (Domain)（而不是 “网址前缀”）。
    • 输入你的域名（不带 https，如 codebearjourney.top）。
    • 系统会弹出一个对话框，复制显示的 TXT 记录值（通常以 google-site-verification= 开头）。
  2. Cloudflare 配置：

    • 登录 Cloudflare Dashboard，进入你的域名页面。

    • 点击左侧菜单 DNS -> Records。

    • 点击 Add record 按钮：

      • Type: 选择 TXT
      • Name: 输入 @ (代表根域名)
      • Content: 粘贴刚才复制的 google-site-verification=... 字符串
      • TTL: 保持 Auto

    • 点击 Save。

  3. 完成验证：
    • 回到 Google Search Console 页面，点击 验证 按钮。通常会立即提示“已验证所有权”。

Bing Webmaster Tools
微软提供了一个极其高效的“偷懒”路径：

  1. 登录 Bing Webmaster Tools。
  2. 选择 “Import from Google Search Console“（从 GSC 导入）。
  3. 授权你的 Google 账号，Bing 会自动同步你的站点验证状态和 Sitemap 地址，无需再手动添加 DNS 记录。

7.3 提交 Sitemap

验证通过后，别忘了最后一步：

  1. 确认 https://codebearjourney.top/sitemap.xml 可以访问。
  2. 在 Google/Bing 后台的 Sitemaps 菜单中，填入 sitemap.xml 并提交。

8. 多端同步工作流

由于采用了 Submodule 和标准化的 npm 依赖管理，在新设备上恢复工作流极其简单：

1
2
3
4
5
6
7
8
9
# 1. 克隆主仓库
git clone git@github.com:tianyuxbear/hexo-blog.git
cd hexo-blog

# 2. 递归恢复子模块 (还原 fluid 主题)
git submodule update --init --recursive

# 3. 恢复插件依赖 (根据 package.json)
npm install

至此，环境完全复刻，可以开始写作了。

参考

  1. Hexo官方文档 ↩
  2. Hexo Fluid 用户手册 ↩
  3. Hello My World ↩
  4. Hexo配置与扩展 ↩
配置指南 > 博客搭建
#Hexo #Fluid #CI/CD
基于 Fluid 的高可用 Hexo 博客实践
https://codebearjourney.top/tutorials/hexo-fluid-guide
作者
Tianyu Xiong
发布于
2025年12月24日
更新于
2025年12月25日
许可协议