Hexo Fluid 主题安装配置完全指南

前言

Fluid 是一款基于 Material Design 风格的 Hexo 博客主题，以其简洁优雅的设计和丰富的配置选项受到广泛欢迎。本文详细介绍 Fluid 主题的安装配置方法、高频使用功能和实用技巧，帮助你快速搭建个性化博客。

一、主题安装

1.1 环境要求

Fluid 主题安装前需确保已安装以下环境：

  • Node.js：建议 16.0 及以上版本
  • Hexo：7.0 及以上版本
  • Git：用于版本控制

1.2 安装步骤

方式一：NPM 安装（推荐）

1
npm install --save hexo-theme-fluid

安装完成后，主题文件会自动放置在 node_modules/hexo-theme-fluid 目录中。

方式二：Git 克隆

1
2
cd themes
git clone https://github.com/fluid-dev/hexo-theme-fluid.git fluid

1.3 启用主题

编辑 Hexo 根目录下的 _config.yml 配置文件，修改主题配置项：

1
2
# _config.yml
theme: fluid

同时，确保语言设置正确，中文用户建议设置为：

1
language: zh-CN

二、基础配置

2.1 配置文件说明

Fluid 主题采用独立的 _config.fluid.yml 配置文件，位于 Hexo 根目录下。该文件包含所有主题相关的配置选项，修改后无需重启服务器即可生效。

2.2 全局基础配置

网站信息

1
2
3
4
5
6
7
8
9
10
# _config.fluid.yml

# 网站图标（浏览器标签页）
favicon: /images/logo.png

# 苹果设备图标
apple_touch_icon: /images/logo.png

# 标签页标题分隔符
tab_title_separator: " - "

导航栏配置

1
2
3
4
5
6
7
8
9
10
11
navbar:
  # 导航栏左侧标题
  blog_title: "博客名称"

  # 导航菜单
  menu:
    - { key: "home", link: "/", icon: "iconfont icon-home-fill" }
    - { key: "archive", link: "/archives/", icon: "iconfont icon-archive-fill" }
    - { key: "category", link: "/categories/", icon: "iconfont icon-category-fill" }
    - { key: "tag", link: "/tags/", icon: "iconfont icon-tags-fill" }
    - { key: "about", link: "/about/", icon: "iconfont icon-user-fill" }

2.3 首页配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
index:
  # 首页 Banner 图片
  banner_img: /img/default.png
  banner_img_height: 100

  # Banner 遮罩透明度
  banner_mask_alpha: 0.3

  # 首页副标题
  slogan:
    enable: true
    text: "技术 · 成长 · 分享"

  # 自动截取文章摘要
  auto_excerpt:
    enable: true

  # 文章元信息显示
  post_meta:
    date: true
    category: true
    tag: true

2.4 页脚配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
footer:
  # 页脚内容（支持 HTML）
  content: '
    <a href="https://hexo.io" target="_blank">Hexo</a> |
    <a href="https://github.com/fluid-dev/hexo-theme-fluid" target="_blank">Fluid</a>
  '

  # 访问统计
  statistics:
    enable: true
    source: "busuanzi"  # 可选: busuanzi | leancloud | umami | openkounter

  # 备案信息
  beian:
    enable: false
    icp_text: "你的ICP备案号"

三、高频使用功能

3.1 代码高亮

Fluid 内置代码高亮功能，支持多种主题样式。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
code:
  # 复制代码按钮
  copy_btn: true

  # 代码语言标识
  language:
    enable: true
    default: "TEXT"

  # 高亮库配置
  highlight:
    enable: true
    line_number: true
    lib: "highlightjs"  # 可选: highlightjs | prismjs
    highlightjs:
      style: "github gist"      # 亮色主题
      style_dark: "dark"       # 暗色主题

3.2 暗色模式

1
2
3
4
dark_mode:
  enable: true
  # 默认模式: auto（自动跟随系统）| light | dark
  default: auto

暗色模式开启后，导航栏会自动出现切换按钮，用户的偏好设置会保存在浏览器本地。

3.3 文章功能

文章页面配置

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
35
post:
  banner_img: /img/default.png
  banner_img_height: 70

  # 文章元信息
  meta:
    author:
      enable: false
    date:
      enable: true
      format: "LL a"
    wordcount:
      enable: true
    min2read:
      enable: true
      awl: 2
      wpm: 60
    views:
      enable: true
      source: "busuanzi"

  # 侧边目录
  toc:
    enable: true
    expand_all: true
    placement: right

  # 版权声明
  copyright:
    enable: true
    license: 'BY-NC-SA'
    author:
      enable: true
    post_date:
      enable: true

文章置顶

在文章 Front-matter 中添加 sticky 属性，数值越大优先级越高：

1
2
3
4
5
---
title: 文章标题
date: 2026-05-05
sticky: 100
---

3.4 搜索功能

Fluid 内置搜索功能，需配合 hexo-generator-search 插件使用。

1
2
3
4
5
6
search:
  enable: true
  path: /local-search.xml
  generate_path: /local-search.xml
  field: post
  content: true

确保已安装搜索插件：

1
npm install hexo-generator-search --save

3.5 数学公式

Fluid 支持 MathJax 和 KaTeX 两种渲染引擎。

启用 MathJax：

1
2
3
4
post:
  math:
    enable: true
    engine: mathjax

单独文章启用：在 Front-matter 中添加 math: true

3.6 Mermaid 流程图

1
2
3
4
post:
  mermaid:
    enable: true
    options: { theme: 'default' }

使用示例：

1
2
3
4
5
6
```mermaid
graph TD
    A[开始] --> B{判断}
    B -->|条件1| C[结果1]
    B -->|条件2| D[结果2]
```

3.7 评论系统

Fluid 支持多种评论插件，启用前需先配置评论：

1
2
3
4
post:
  comments:
    enable: true
    type: gitalk  # 选择评论插件

常用评论插件配置：

Gitalk（基于 GitHub Issues）：

1
2
3
4
5
6
7
gitalk:
  clientID: '你的GitHub Client ID'
  clientSecret: '你的GitHub Client Secret'
  repo: '你的仓库名'
  owner: '你的GitHub用户名'
  admin: ['你的GitHub用户名']
  language: zh-CN

Valine（基于 LeanCloud）：

1
2
3
4
5
valine:
  appId: '你的App ID'
  appKey: '你的App Key'
  placeholder: '说点什么吧...'
  avatar: 'retro'

3.8 访问统计

1
2
3
4
5
6
7
8
9
10
11
12
13
14
web_analytics:
  enable: true

  # 百度统计
  baidu: '你的百度统计Key'

  # Google Analytics 4
  google:
    measurement_id: '你的GA4 Measurement ID'

  # LeanCloud 统计
  leancloud:
    app_id: '你的App ID'
    app_key: '你的App Key'

四、自定义页面创建

4.1 关于页

1
hexo new page about

编辑 source/about/index.md：

1
2
3
4
5
6
7
8
9
---
title: 关于
date: 2026-05-05
layout: about
---

# 个人介绍

这里写你的个人介绍内容...

配置关于页显示信息：

1
2
3
4
5
6
7
8
about:
  enable: true
  avatar: /img/avatar.png
  name: "你的名字"
  intro: "个人简介"
  icons:
    - { class: "iconfont icon-github-fill", link: "https://github.com", tip: "GitHub" }
    - { class: "iconfont icon-wechat-fill", qrcode: "/img/wechat.jpg" }

4.2 分类页

1
hexo new page categories

编辑 source/categories/index.md：

1
2
3
4
5
6
---
title: 分类
date: 2026-05-05
layout: categories
type: categories
---

4.3 标签页

1
hexo new page tags

编辑 source/tags/index.md：

1
2
3
4
5
6
---
title: 标签
date: 2026-05-05
layout: tags
type: tags
---

4.4 友链页

1
hexo new page links

编辑 source/links/index.md：

1
2
3
4
5
---
title: 友情链接
date: 2026-05-05
layout: links
---

配置友链内容：

1
2
3
4
links:
  enable: true
  items:
    - { title: "示例网站", intro: "网站简介", link: "https://example.com", avatar: "/img/friend.jpg" }

五、Front-matter 技巧

Front-matter 是文章头部的元数据区域，合理使用可以精细控制文章显示效果。

5.1 常用字段

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
---
title: 文章标题
date: 2026-05-05 10:30:00
updated: 2026-05-06 15:00:00
tags:
  - 标签1
  - 标签2
categories:
  - 分类1
  - 分类2
  - 分类2-1
author: 作者名
cover: /img/cover.jpg    # 文章封面图
excerpt: 文章摘要...      # 自定义摘要
toc: true                # 是否显示目录
math: true               # 启用数学公式
mermaid: true            # 启用Mermaid
sticky: 100               # 置顶优先级
---

5.2 文章封面图

Fluid 支持为每篇文章设置独立封面图：

  • cover：指定封面图片路径
  • 默认封面：当未指定 cover 时使用 post.default_index_img，若也未设置则不显示封面
1
2
3
4
---
title: 示例文章
cover: /img/posts/example-cover.jpg
---

5.3 文章加密

如需对文章进行加密访问，可在 Front-matter 中添加密码验证：

1
2
3
4
---
title: 私密文章
password: 123456
---

六、自定义样式与脚本

6.1 自定义 CSS

创建 source/css/custom.css 文件，编辑配置：

1
2
custom_css:
  - /css/custom.css

6.2 自定义 JavaScript

创建 source/js/custom.js 文件，编辑配置：

1
2
custom_js:
  - /js/custom.js

6.3 常用自定义示例

修改链接下划线样式：

1
2
3
4
5
6
7
8
.markdown-body a {
  text-decoration: none;
  border-bottom: 1px solid currentColor;
}

.markdown-body a:hover {
  border-bottom-width: 2px;
}

自定义代码块背景：

1
2
3
4
.markdown-body pre {
  background: #f6f8fa;
  border-radius: 6px;
}

七、性能优化

7.1 图片懒加载

1
2
3
4
5
lazyload:
  enable: true
  loading_img: /img/loading.gif
  onlypost: false
  offset_factor: 2

7.2 CDN 配置

Fluid 支持自定义静态资源 CDN，适合有特殊需求的用户：

1
2
3
4
static_prefix:
  internal_js: /js
  internal_css: /css
  internal_img: /img

7.3 代码压缩

安装 hexo-filter-cleanup 插件减少静态文件体积：

1
npm install hexo-filter-cleanup --save

八、常见问题

8.1 页面不更新

执行清理缓存命令：

1
hexo clean && hexo g

8.2 样式错乱

检查是否有自定义 CSS 与主题样式冲突，尝试禁用自定义样式排查问题。

8.3 评论不显示

确认评论插件配置正确，特别是 GitHub 相关配置需要确保：

  • 已创建 GitHub OAuth Application
  • 回调地址填写正确
  • 域名配置与实际访问地址一致

8.4 数学公式渲染异常

确保 Markdown 渲染器与数学公式插件兼容，建议使用官方推荐的渲染器组合：

1
2
npm uninstall hexo-renderer-marked
npm install hexo-renderer-kramed --save

九、部署发布

9.1 本地预览

1
2
3
hexo server
# 或简写
hexo s

访问 http://localhost:4000 查看效果。

9.2 生成静态文件

1
2
3
hexo generate
# 或简写
hexo g

9.3 部署到 GitHub Pages

配置 GitHub Actions 或使用 hexo-deployer-git 插件：

1
npm install hexo-deployer-git --save

编辑 _config.yml：

1
2
3
4
deploy:
  type: git
  repo: https://github.com/username/username.github.io.git
  branch: gh-pages

部署命令：

1
2
3
hexo deploy
# 或简写
hexo d

十、进阶配置建议

10.1 SEO 优化

1
2
3
4
5
6
7
# 站点配置文件 _config.yml
url: https://yourdomain.com
root: /

# Fluid 配置
canonical:
  enable: true

10.2 Open Graph 优化

1
2
3
4
5
open_graph:
  enable: true
  twitter_card: summary_large_image
  twitter_id: "你的Twitter账号"
  twitter_site: "你的Twitter账号"

10.3 sitemap 生成

安装插件生成站点地图：

1
2
npm install hexo-generator-sitemap --save
npm install hexo-generator-baidu-url --save  # 百度专用

结语

Fluid 主题以其灵活的配置和优雅的设计，为 Hexo 博客提供了出色的视觉体验。通过本文的介绍，你应该能够顺利完成主题的安装配置，并掌握高频使用功能的设置方法。建议从基础配置开始，逐步尝试高级功能，打造属于自己的个性化博客。

如需了解更多高级用法，请访问 Fluid 官方文档。

技术教程
#Hexo #Fluid #博客
Hexo Fluid 主题安装配置完全指南
https://www.v-bao.com/post/hexo-fluid-主题安装配置完全指南.html
作者
John Doe
发布于
2026年5月5日
许可协议