Hexo Fluid 主题详细使用教程

一、安装主题

方法一：npm 安装（推荐）

npm install --save hexo-theme-fluid

方法二：下载 Release 包

前往 GitHub Releases 下载最新版本，解压到博客 themes/fluid 目录。

激活主题

编辑博客根目录的 _config.yml：

theme: fluid
language: zh-CN

# 关闭 Hexo 默认代码高亮（交给主题处理）
highlight:
  enable: false

---

二、覆盖配置（重要！）

Hexo 5.0.0 以上用户，在博客目录下创建 _config.fluid.yml 文件，将主题的 _config.yml 全部配置（或部分配置）复制过去，以后修改主题配置只需改这个文件，避免更新主题时丢失配置。

存在于 _config.fluid.yml 的配置都是高优先级，修改原 _config.yml 无效。

想验证覆盖配置是否生效，可以运行：

hexo g --debug

---

三、创建「关于」页面

首次使用主题的「关于页」需要手动创建：

hexo new page about

创建成功后修改 /source/about/index.md，添加 layout 属性：

---
title: 关于
layout: about
---

---

四、核心配置详解

4.1 Banner 顶部大图

主题配置中，每个页面都有 banner_img 属性，可以使用本地图片的相对路径，也可以为外站链接。本地图片必须放在 source 目录下，图片大小建议压缩到 1MB 以内，否则会严重拖慢页面加载。banner_img_height 有效值为 0–100，100 即为全屏，个人建议 70 以上。

index:
  banner_img: /img/your_banner.jpg
  banner_img_height: 80
  slogan:
    enable: true
    text: "你的个性签名"

4.2 首页文章列表

index:
  post_meta:       # 文章信息
    date: true     # 发布时间
    wordcount: true  # 字数统计
    category: true   # 分类
    tag: true        # 标签
  post_img:
    enable: true           # 显示封面图
    default: /img/default.png  # 默认封面

4.3 文章置顶

如果想手动将某些文章固定在首页靠前的位置，可以在安装 hexo-generator-index >= 2.0.0 版本的情况下，在文章开头的 front-matter 中配置 sticky 属性：

---
title: 我的置顶文章
sticky: 100  # 数字越大越靠前
---

4.4 文章封面图（单篇）

对于单篇文章，在文章开头 front-matter 中配置 index_img 属性，路径规则与 Banner 配置相同，/img/example.jpg 对应 /source/img/example.jpg：

---
title: 文章标题
index_img: /img/post_cover.jpg
---

---

五、功能扩展配置

5.1 本地搜索

主题已集成 hexo-generator-search 插件，默认在根目录生成并使用 local-search.xml。若已安装其他搜索插件请关闭，以避免生成多余的索引文件。

npm install hexo-generator-search --save

_config.fluid.yml 中无需额外配置，主题默认开启。

5.2 评论系统

主题支持多种评论系统，选项包括：utterances | disqus | gitalk | valine | waline | changyan | livere | remark42 | twikoo | cusdis | giscus | discuss。

开启评论需要先设置 post: comments: enable: true，然后根据 type 设置对应评论插件参数：

post:
  comments:
    enable: true
    type: giscus  # 推荐 giscus（基于 GitHub Discussions）

5.3 数学公式 & 流程图

对于 Mermaid 流程图，开启后只有在文章 front-matter 里指定 mermaid: true 才会在文章页启动渲染，以便在页面不包含流程图时提高加载速度。

# 数学公式（KaTeX）
post:
  math:
    enable: true
    specific: true  # true = 只有 front-matter 里 math: true 才加载

# Mermaid 流程图
post:
  mermaid:
    enable: true
    specific: true

5.4 统计 & 页脚 PV/UV

目前支持多种统计网站，开启后按需填入 Key 或 ID 即可；页脚可以展示 PV 与 UV 统计数据，目前支持「不蒜子」等数据来源：

web_analytics:
  enable: true
  # 支持 Google Analytics、百度统计等

footer:
  statistics:
    enable: true
    source: busuanzi  # 不蒜子
    pv_format: "总访问量 {} 次"
    uv_format: "总访客数 {} 人"

---

六、自定义语言 / 多语言

可以使用类似于覆盖配置的方式去自定义语言：进入博客目录的 source/_data 目录（不存在则创建），创建 languages 文件夹，在其中创建 zh-CN.yml 等文件，将 fluid/languages 目录下对应语言的配置内容复制进去，以后在此文件中修改，配置会在 hexo g 时自动覆盖。

---

七、CDN 加速静态资源

所有静态资源文件的 URL 可以通过主题配置中的 static_prefix 配置项修改，比如需要指定公共 CDN 的 jQuery 库，只需将原配置改为对应 CDN 地址：

static_prefix:
  jquery: https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/

---

八、常用操作命令

hexo clean  # 清除缓存（每次修改配置后建议先执行）
hexo g      # 生成静态文件
hexo s      # 本地预览
hexo d      # 部署

---

九、注意事项

• 本指南中提到的 source 目录都指的是博客目录下的 source 文件夹，不推荐修改主题内 source 目录
• 每次 hexo g 或 hexo s 之前，都最好先使用 hexo clean 清除本地缓存
• 部署后的异常大部分是线上缓存原因，在确认没有报错的情况下等待若干时间即可恢复正常

---

官方文档：https://fluid-dev.github.io/hexo-fluid-docs/guide/