Hexo + Fluid 主题配置 giscus 评论的完整教程

第一步：准备 GitHub 仓库

你需要一个用于存放评论数据的 GitHub 仓库（可以直接复用你博客部署的仓库，也可以新建一个专用仓库）。

  1. 确保仓库为 Public
  2. 进入仓库 → Settings → Features → 勾选 Discussions
  3. 访问 github.com/apps/giscus 将 giscus App 授权安装到该仓库

第二步：在 giscus.app 生成配置参数

访问 https://giscus.app/zh-CN，填写以下内容：

  • 仓库：输入 your-name/your-repo，验证通过后继续
  • 页面与 Discussion 的映射：推荐选 pathname
  • Discussion 分类：推荐选 Announcements（只有仓库维护者和 giscus 能创建新话题，防止手动乱建）
  • 功能：按需勾选「启用表情反应」等

生成的 <script> 中，你需要记下以下几个关键值：

1
2
3
4
data-repo="your-name/your-repo"
data-repo-id="R_xxxxxxxxxx"         <!-- repo_id -->
data-category="Announcements"
data-category-id="DIC_xxxxxxxxxx"   <!-- category_id -->

第三步：确认 Fluid 主题版本支持 giscus

如果你的 Fluid 版本较旧，可能尚未支持 giscus，需要先将主题更新到支持 giscus 的版本。

可以在主题配置文件中搜索 giscus 关键字确认是否存在相关配置项。Fluid 主题的 _config.yml 中，post.comments.type 支持的插件选项包括：

1
utterances | disqus | gitalk | valine | waline | changyan | livere | remark42 | twikoo | cusdis | giscus | discuss

第四步：修改主题配置文件

⚠️ 注意：「主题配置」指的是 themes/fluid/_config.yml 或者博客根目录下的 _config.fluid.yml，两者二选一，后者优先级更高且在主题更新时不会丢失，推荐使用后者。

4.1 开启评论并指定类型为 giscus

在主题配置文件中找到 post.comments 部分，修改为：

1
2
3
4
post:
  comments:
    enable: true
    type: giscus

4.2 填写 giscus 参数

在配置文件中找到 giscus: 节，填入第二步获取的参数：

1
2
3
4
5
6
7
8
9
10
11
12
giscus:
  repo: your-name/your-repo          # 格式：用户名/仓库名
  repo_id: R_xxxxxxxxxx              # 从 giscus.app 获取
  category: Announcements            # Discussion 分类名称
  category_id: DIC_xxxxxxxxxx        # 从 giscus.app 获取
  theme:                             # 主题样式
    light: light                     # 亮色模式
    dark: dark                       # 暗色模式（Fluid 支持自动切换）
  input_position: bottom             # 评论框位置：top | bottom
  lang: zh-CN                        # 语言
  mapping: pathname                  # 页面映射方式
  reactions_enabled: 1               # 是否开启表情反应：1 开启，0 关闭

⚠️ 常见踩坑提示：网络上流传的一些 giscus yml 配置代码，实际上是 hexo-next-giscus 插件的模板，并不是 Fluid 主题原生支持的格式，不要混用。请以 Fluid 主题自带的 _config.yml 中的 giscus 节为准。

第五步：本地验证与部署

1
2
hexo clean    # 清除缓存
hexo s        # 本地预览

访问任意文章页面，滚动到底部确认评论组件加载正常。确认无误后：

1
2
hexo g        # 生成静态文件
hexo d        # 部署

可选：单独控制某篇文章的评论

如果某篇文章不想显示评论，可在 front-matter 中关闭：

1
2
3
4
5
---
title: 某篇文章
date: 2024-01-01
comments: false
---

或者指定使用其他评论插件（覆盖全局设置）：

1
comments: 'giscus'

配置总览（完整示例）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 主题配置 _config.fluid.yml

post:
  comments:
    enable: true
    type: giscus          # 指定使用 giscus

giscus:
  repo: your-name/your-repo
  repo_id: R_xxxxxxxxxxxxxxxxxx
  category: Announcements
  category_id: DIC_xxxxxxxxxxxxxxxx
  theme:
    light: light
    dark: dark
  input_position: bottom
  lang: zh-CN
  mapping: pathname
  reactions_enabled: 1

填入你从 giscus.app 获取到的真实 repo_id 和 category_id 后，评论系统即可正常工作。

技术教程
#Hexo #Fluid #giscus #评论系统 #GitHub
Hexo + Fluid 主题配置 giscus 评论的完整教程
https://iomelons.github.io/2026/03/23/cmn6ntccc0008sk2198x313pk/
作者
iomelons
发布于
2026年3月23日
许可协议