Hexo 博客接入 Giscus 评论系统

前言

在搭建个人博客时，评论系统是一个很常见的需求。

以前常见的评论方案有 Valine、Twikoo、Waline、Utterances 等。本文记录的是另一种基于 GitHub Discussions 的评论系统：Giscus。

Giscus 可以把 GitHub Discussions 集成到网站中作为评论区。它的主要好处是：

1
2
3
评论数据存储在 GitHub 上
不需要自己维护数据库
适合 GitHub Pages、Hexo、Hugo 等静态博客

官方地址：https://giscus.app/

可以把 Giscus 理解成：

  1. 博客文章页面
  2. 嵌入 Giscus 评论组件
  3. 评论内容自动保存到 GitHub Discussions

也就是说，博客本身只负责展示评论区，真正的评论数据由 GitHub 仓库管理。

一、准备 GitHub 评论仓库

1.1 新建评论仓库

Giscus 的评论数据需要存放在 GitHub Discussions 中，因此需要准备一个 GitHub 仓库。

这个仓库可以和博客源码仓库分开，也可以使用已有仓库。为了方便管理，建议单独新建一个评论仓库。

例如：

1
2
3
comment-utterances
comments
blog-comments

新建仓库如下：

image-20260606143216315

需要注意的是，Giscus 要求评论仓库必须是公开仓库。

1.2 开启 Discussions 功能

新建仓库之后，还需要开启 GitHub Discussions 功能。

进入仓库页面后，依次点击：Settings → General → Features

然后找到 Discussions 选项并勾选。

image-20260606143432042

image-20260606143529523

Giscus 的评论内容本质上就是一条条 GitHub Discussion。

可以简单理解为：

一篇博客文章对应一个 GitHub Discussion，读者评论就是 Discussion 下面的回复

所以如果没有开启 Discussions，Giscus 就无法正常工作。

二、安装 Giscus 并生成配置代码

2.1 安装 Giscus GitHub App

接下来需要给 GitHub 仓库安装 Giscus 应用。

安装地址：https://github.com/apps/giscus

打开页面后，点击安装。

image-20260606143647641

安装时可以选择允许 Giscus 访问哪些仓库。

建议选择：Only select repositories

然后选择刚才新建的评论仓库。

这样可以避免 Giscus 访问不相关的仓库，更安全也更清晰。

image-20260606143901225

选择完成后，点击 Install 安装即可。

2.2 进入 Giscus 官网配置

安装完 GitHub App 后，进入 Giscus 中文配置页面：https://giscus.app/zh-CN

在这里填写仓库、页面映射、评论分类、主题等信息。

image-20260606152558171

首先语言建议选择：

1
简体中文

这样博客评论区中的按钮和提示文字都会显示为中文。

对应生成代码中的字段是：

1
data-lang="zh-CN"

Repository 这里填写 GitHub 仓库信息，推荐格式为：

1
用户名/仓库名

例如：

1
likerhood/comment-utterances

如果配置成功，页面会出现绿色提示，说明当前仓库满足 Giscus 的使用条件。

一般需要满足三个条件：

1
2
3
1. 仓库是公开仓库
2. 已经安装 Giscus App
3. 已经开启 Discussions 功能

2.3 选择页面映射和评论分类

Giscus 需要知道当前博客文章应该对应 GitHub Discussions 里的哪一个 discussion。

这就需要选择一个映射规则。

可以把它理解成：

1
博客文章和 GitHub Discussion 之间的绑定规则

对于 Hexo 博客来说，推荐选择：

1
Discussion title contains page pathname

对应生成代码中的字段是：

1
data-mapping="pathname"

这样每篇文章会根据自己的 URL 路径生成对应评论区。

例如文章路径是：

1
/2026/06/06/hexo-giscus/

那么 Giscus 就会根据这个路径去查找或者创建对应的 Discussion。

接着选择 Discussion 分类。Giscus 会把评论内容存放到 GitHub Discussions 的某个分类中。

常见分类有：

1
2
3
4
Announcements
General
Q&A
Ideas

如果是博客评论，通常可以选择：

1
General

对应生成代码中的字段类似：

1
2
data-category="General"
data-category-id="DIC_xxxxx"

其中 data-category-id 是 Giscus 自动生成的分类 ID，不建议手动修改，直接复制官网生成的即可。

2.4 复制生成的 script 代码

配置完成后，在页面底部会生成一段 <script> 代码。

image-20260606152653449

代码大概类似：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<script src="https://giscus.app/client.js"
        data-repo="用户名/仓库名"
        data-repo-id="仓库ID"
        data-category="Announcements"
        data-category-id="分类ID"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        crossorigin="anonymous"
        async>
</script>

这里最重要的是下面几个字段：

1
2
3
4
5
6
7
data-repo：评论仓库
data-repo-id：仓库 ID
data-category：Discussions 分类名
data-category-id：Discussions 分类 ID
data-mapping：文章和 discussion 的映射方式
data-theme：评论区主题
data-lang：评论区语言

这些信息直接从官网复制即可，不建议自己手动乱改。

三、接入 Hexo 博客并部署

3.1 如果主题支持 Giscus

很多 Hexo 主题已经内置了 Giscus 配置，例如 Butterfly、Anzhiyu、NexT 等。

这时不需要手动插入完整 <script>，只需要在主题配置文件中填写对应字段即可。

常见配置文件可能是：

1
2
3
4
_config.yml
_config.butterfly.yml
_config.anzhiyu.yml
themes/主题名/_config.yml

可以在博客源码中搜索：

1
2
3
giscus
comment
comments

找到对应配置位置。

配置格式通常类似：

1
2
3
4
5
6
7
8
9
10
11
12
13
giscus:
  enable: true
  repo: 用户名/仓库名
  repo_id: 仓库ID
  category: Announcements
  category_id: 分类ID
  mapping: pathname
  strict: 0
  reactions_enabled: 1
  emit_metadata: 0
  input_position: bottom
  theme: preferred_color_scheme
  lang: zh-CN

不同主题的字段名可能略有不同，具体以主题文档为准。

3.2 如果主题不支持 Giscus

如果当前 Hexo 主题没有内置 Giscus，就需要手动把官方生成的 <script> 加到文章页面模板中。

常见位置可能是：

1
2
3
themes/主题名/layout/_partial/comments.ejs
themes/主题名/layout/post.ejs
themes/主题名/layout/_partial/article.ejs

大致思路是：

1
找到文章页面底部,找到评论区位置,把 Giscus 的 script 代码粘贴进去

例如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<div class="giscus"></div>

<script src="https://giscus.app/client.js"
        data-repo="用户名/仓库名"
        data-repo-id="仓库ID"
        data-category="Announcements"
        data-category-id="分类ID"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        crossorigin="anonymous"
        async>
</script>

其中：

1
<div class="giscus"></div>

可以理解为给评论区预留一个位置。Giscus 加载后，会自动把评论组件渲染到这个位置。

3.3 重新生成并部署

配置完成后，回到 Hexo 博客根目录，执行：

1
2
3
hexo clean
hexo g
hexo s

然后打开本地预览地址，检查文章底部是否正常显示评论区。

如果本地显示正常，再执行部署命令：

1
2
3
hexo d
# 或者执行
hexo g -d

部署完成后，进入线上博客文章页面，查看评论区是否正常加载。

总结

本文记录了在 Hexo 博客中接入 Giscus 评论系统的完整流程。

核心步骤可以总结为：

  1. 新建 GitHub 评论仓库
  2. 开启 Discussions 功能
  3. 安装 Giscus GitHub App
  4. 进入 Giscus 官网生成配置
  5. 复制 repo、repo-id、category-id 等信息
  6. 加入 Hexo 主题配置或文章模板
  7. 重新生成并部署博客

Giscus 的优点是配置简单、数据托管在 GitHub、适合静态博客使用。

对于使用 GitHub Pages 和 Hexo 搭建的个人博客来说，Giscus 是一个比较轻量、干净、方便管理的评论系统。