Hexo添加评论系统

发表于 更新于 分类于

在参照了网上众多教程后最终成功进行了 Giscus 评论系统配置（个人是基于 Hexo + Next主题），写下这篇文章用于记录，希望能够帮助到别人。

Hexo 作为静态博客系统，自身不具备动态评论功能，需借助第三方服务实现。本文记录基于 Hexo + Next 主题 配置 Giscus 评论系统的全流程操作，Giscus 依托 GitHub Discussions 构建，具有以下核心优势：

  • 完全开源，代码透明可自建
  • 无广告、无追踪、永久免费
  • 无需自建数据库，所有评论数据存储在你的 GitHub 仓库中
  • 支持自定义主题、多语言、明暗模式适配
  • 访客通过 GitHub 账号即可评论，无需额外注册

前置准备

在开始配置前，请确保你已满足以下条件：

  1. 拥有一个 公开的（Public） GitHub 仓库（用于存储评论，即你的博客仓库）；
  2. 仓库已开启 GitHub Pages 服务（Hexo 博客通常已满足）。

步骤1：安装 Giscus GitHub App

这一步是让 Giscus 获得访问你仓库 Discussions 的权限，操作如下：

  1. 访问 Giscus GitHub App；
  2. 点击 Install 按钮；
  3. 在 Repository access 中选择 Only select repositories；
  4. 在下拉列表中选中你的博客仓库（如 JinYang0418/JinYang0418.github.io）；
  5. 点击 Install & Authorize 完成授权安装。

步骤2：启用仓库 Discussions 功能

Giscus 依赖 GitHub Discussions 存储评论，需手动开启：

  1. 进入你的博客仓库，点击顶部 Settings 标签；
  2. 在左侧菜单找到 Features 区域；
  3. 勾选 Discussions 选项，启用后仓库顶部会出现 Discussions 标签页。

步骤3：在 Giscus 官网生成配置代码

访问 Giscus 官网完成可视化配置，获取关键参数：

  1. 打开 Giscus 官网（中文）；
  2. 下拉到 配置 区域，按以下建议选择（可根据需求调整）：
配置项 推荐选择 说明
语言 zh-CN 界面显示为中文
仓库 选择你的博客仓库 需确保仓库公开、已安装 Giscus、已开启 Discussions
页面 ↔️ Discussion 映射关系 title Discussion 标题直接使用文章标题，中文显示友好且匹配精准
使用严格的标题匹配 0（关闭） 避免因标题细微差异导致匹配失败
Discussion 分类 Announcements（公告） 推荐选择，该分类仅仓库维护者可创建新 Discussion，访客可正常评论，避免无关讨论
只搜索该分类中的 Discussion 勾选 确保评论仅匹配指定分类
启用主帖子上的反应 勾选 在评论区顶部显示文章的表情回应
输出 Discussion 的元数据 不勾选 按需选择，一般无需开启
将评论框放在评论上方 不勾选 评论框默认在底部，符合阅读习惯
懒加载评论 勾选 提升页面加载速度，评论滚动到可视区域时再加载
主题 preferred_color_scheme 跟随系统明暗模式自动切换
  1. 配置完成后，下拉到 启用 giscus 区域，会自动生成一段 <script> 代码，复制并保存这段代码，后续需要从中提取关键参数：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<script src="https://giscus.app/client.js"
        data-repo="JinYang0418/JinYang0418.github.io"
        data-repo-id="R_kgDOSDKEeQ"
        data-category="Announcements"
        data-category-id="DIC_kwDOSDKEec4C643t"
        data-mapping="title"
        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>

步骤 4：在 Hexo Next 主题中配置 Giscus

Next 主题可通过插件快速集成 Giscus，无需手动修改主题代码。

  1. 安装 hexo-next-giscus 插件

在 Hexo 博客根目录打开终端，执行以下命令：

1
npm install hexo-next-giscus --save
  1. 编辑配置文件

在 Hexo 站点配置文件 _config.yml（推荐，避免主题更新后配置丢失）或 Next 主题配置文件 _config.next.yml 中，添加如下配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Giscus 评论系统配置
giscus:
  enable: true                  # 开启 Giscus
  repo: "JinYang0418/JinYang0418.github.io"  # 你的博客仓库（格式：用户名/仓库名）
  repo_id: "R_kgDOSDKEeQ"      # 从 Giscus 生成的代码中提取 data-repo-id
  category: "Announcements"     # 从 Giscus 生成的代码中提取 data-category
  category_id: "DIC_kwDOSDKEec4C643t"  # 从 Giscus 生成的代码中提取 data-category-id
  mapping: "title"              # 页面与 Discussion 的映射方式，与 Giscus 官网配置一致
  strict: "0"                   # 是否严格匹配标题，与 Giscus 官网配置一致
  reactions_enabled: "1"        # 是否启用表情回应，1=开启，0=关闭
  emit_metadata: "0"            # 是否输出元数据，1=开启，0=关闭
  input_position: "bottom"      # 评论框位置，bottom=底部，top=顶部
  theme: "preferred_color_scheme"  # 主题，与 Giscus 官网配置一致
  lang: "zh-CN"                 # 界面语言
  loading: "lazy"               # 是否懒加载，lazy=开启
  1. 核心参数详细说明
参数名 详细说明
enable Giscus 评论系统的总开关，设置为 true 即可启用
repo 用于存储评论的 GitHub 仓库，固定格式为 GitHub用户名/仓库名
repo_id 仓库的唯一标识 ID，必须从 Giscus 官网生成的 data-repo-id 中提取
category 评论存放的 Discussion 分类名称，需与 Giscus 官网配置一致
category_id 分类的唯一标识 ID，必须从 Giscus 官网生成的 data-category-id 中提取
mapping 页面与 Discussion 的映射规则，可选值：url/pathname/title/og:title/specific/number
strict 是否开启严格标题匹配，开启后可避免相似标题的错误匹配，常规使用建议关闭
reactions_enabled 控制是否在评论区顶部显示文章的表情回应功能
input_position 控制评论输入框的位置，可设置为顶部或底部
theme 评论区主题，可选值：light/dark/preferred_color_scheme/noborder_light/noborder_dark 等
lang 评论系统的显示语言，简体中文固定为 zh-CN
loading 评论加载模式，设置为 lazy 开启懒加载，优化页面加载性能

步骤5：部署上线与效果验证

  1. 配置完成后，在 Hexo 博客根目录的终端中，执行部署命令：
1
hexo clean && hexo g && hexo d
  1. 部署完成后，访问你的博客任意文章页面，下拉至文章底部的评论区：
  • 若正常显示 Giscus 评论框与登录入口，说明基础配置成功；
  • 点击评论框，会跳转至 GitHub OAuth 授权页面，完成授权后即可发布评论；
  • 评论发布后，会自动同步到 GitHub 仓库的 Discussions 标签页对应分类中，你可直接在 GitHub 上管理、回复、删除评论。

常见问题排查

  1. 评论区显示「仓库未找到」或「Discussion 未找到」

排查要点：

  • 确认仓库为 公开（Public） 状态，私有仓库无法正常使用；
  • 确认 Giscus GitHub App 已正确安装到该仓库，且已授予完整权限；
  • 确认仓库已开启 Discussions 功能；
  • 核对配置文件中的 repo/repo_id/category/- category_id 与 Giscus 官网生成的代码完全一致，无拼写错误。
  1. 评论框样式与博客主题不匹配

解决方案：

  • 在 Giscus 官网配置中更换适配的主题，如 noborder_light/noborder_dark 无边框主题；
  • 可通过自定义 CSS 代码，修改 .giscus 和 .giscus-frame 选择器的样式，实现深度定制。
  1. 每次 Hexo 部署后，评论配置丢失

排查要点：

  • 确认配置是添加在 Hexo 站点根配置文件 _config.yml 中，而非临时修改主题的源码文件（主题更新后会被覆盖）；
  • 确认 hexo-next-giscus 插件已正确安装，无安装报错。
  1. 访客无法发布评论

排查要点：

  • 确认 Discussion 分类选择的是 Announcements 类型，且已正确配置分类 ID；
  • 确认仓库的 Discussions 权限设置中，已开放普通用户的评论权限。