为 Hexo 博客添加 Giscus 评论系统

为博客添加评论功能是增强互动性的重要一步。这篇文章记录我为 Hexo + Butterfly 博客集成 Giscus 评论系统的完整过程。

为什么选择 Giscus？

在众多评论系统中（Disqus、Gitalk、Valine 等），我选择 Giscus 的原因：

无需数据库：不需要额外的后端服务
支持 Markdown：评论可以使用完整的 Markdown 语法
主题适配：自动适配网站的明暗主题
完全免费：无任何使用限制
隐私友好：不会追踪用户数据

准备工作

1. 创建评论存储仓库

在 GitHub 上创建一个公开仓库用于存储评论数据。

关键设置：

仓库必须是 public（公开）
启用 Discussions 功能：进入仓库 Settings → Features → 勾选 Discussions

2. 安装 Giscus App

访问 Giscus App 并安装到你的评论仓库：

点击 “Install”
选择 “Only select repositories”
选中刚才创建的仓库
授权安装

配置 Giscus

3. 获取配置参数

访问 Giscus 官网进行配置：

① 仓库信息

1	仓库：用户名/仓库名

② Discussion 分类

选择 “Announcements” 类型（推荐），这样只有仓库维护者可以创建新讨论，但所有人都能评论。

③ 映射方式

选择 “pathname”（路径名），这样每篇文章会根据 URL 路径自动创建对应的 Discussion。

④ 主题

选择 “preferred_color_scheme”（跟随系统），自动适配明暗模式。

⑤ 获取关键 ID

配置完成后，Giscus 会生成一段代码，从中提取两个关键参数：

<script src="https://giscus.app/client.js"
        data-repo="用户名/仓库名"
        data-repo-id="XXXXXXXXXXX"          <!-- 这是 repo_id -->
        data-category="Announcements"
        data-category-id="XXXXXXXXXXXX" <!-- 这是 category_id -->
        ...>
</script>

记下 data-repo-id 和 data-category-id 的值。

在 Butterfly 主题中配置

4. 修改主题配置文件

打开 themes/butterfly/_config.yml，找到 comments 部分：

comments:
  # 选择评论系统
  use: giscus
  text: true
  # lazyload: 懒加载评论
  lazyload: false
  # count: 显示评论数
  count: true
  # card_post_count: 在卡片上显示评论数
  card_post_count: true

然后找到 giscus 配置段，填入参数：

giscus:
  repo: 用户名/仓库名
  repo_id: XXXXXXXXXXXXXXXXXX
  category_id: XXXXXXXXXXXXXXXXXX
  theme:
    light: light
    dark: dark
  option:
    data-mapping: pathname
    data-strict: 0
    data-reactions-enabled: 1
    data-emit-metadata: 0
    data-input-position: bottom
    data-lang: zh-CN
    data-loading: lazy

参数说明：

repo: 你的评论仓库（格式：用户名/仓库名）
repo_id: 从 Giscus 获取的仓库 ID
category_id: 从 Giscus 获取的分类 ID
data-mapping: pathname: 使用文章路径作为映射
data-lang: zh-CN: 界面语言设为中文
data-reactions-enabled: 1: 启用表情回应功能

5. 重新生成并部署

1
2
3

hexo clean
hexo generate
hexo deploy

效果验证

部署完成后，访问任意文章页面，应该能看到：

文章底部出现 Giscus 评论框
需要登录 GitHub 才能评论
评论会自动同步到仓库的 Discussions 中
支持 Markdown 格式、代码高亮、表情回应

注意事项

仓库必须公开：私有仓库无法使用 Giscus
确保安装了 Giscus App：否则评论无法加载
Discussions 必须启用：在仓库设置中开启
首次评论会自动创建 Discussion：按文章路径命名
可以在 GitHub 仓库中管理评论：删除、编辑、置顶等