Hexo博客Giscus评论系统配置教程 | Butterfly主题GitHub评论插件安装与使用

🎉 欢迎阅读本教程！
本文将带你详细了解如何在Hexo Butterfly主题中配置和使用Giscus评论系统，适合Hexo博客零基础的用户。

Hexo博客Giscus评论系统配置教程

Giscus是一款基于GitHub Discussions的现代评论系统，具有轻量、美观、无需服务器等优点。当用户在你的博客上发表评论时，评论会被发送到你指定的GitHub仓库的Discussions中，同时实时显示在你的博客页面上。

📋 目录

1. Giscus简介
2. Giscus配置步骤
3. Giscus高级配置
4. Giscus使用技巧
5. 常见问题解决
6. Giscus与其他评论系统对比
7. 总结
8. 参考资料

📖 Giscus简介

在开始配置之前，让我们先了解一下Giscus是什么，以及它的优缺点。

🔹 什么是Giscus？

Giscus是一个开源的评论系统，它创新性地使用GitHub Discussions来存储和管理评论。当用户在你的博客上发表评论时，评论会被发送到你指定的GitHub仓库的Discussions中，同时实时显示在你的博客页面上。

🔹 Giscus的优点

✨ Giscus的核心优势：

• 无需服务器：完全基于GitHub Discussions，不需要自己搭建和维护服务器
• 开源免费：遵循MIT许可证，永久免费使用
• 支持Markdown：用户可以使用Markdown语法发表富文本评论
• GitHub登录：利用GitHub账号登录，无需额外注册
• 自动主题适配：支持浅色和深色主题，自动适配博客主题
• 高度可配置：提供丰富的配置选项，满足个性化需求
• 响应式设计：完美适配各种屏幕尺寸
• 垃圾评论防护：利用GitHub的审核机制，有效防止垃圾评论
• 数据安全：评论数据存储在GitHub，安全可靠

🔹 Giscus的缺点

⚠️ 使用前请注意：

• 依赖GitHub：用户需要有GitHub账号才能评论
• 首次配置稍复杂：需要在GitHub上进行一些设置
• 评论显示延迟：由于需要调用GitHub API，评论显示可能有轻微延迟
• GitHub API限制：如果博客访问量很大，可能会触发GitHub API的速率限制

🚀 Giscus配置步骤

本节将详细介绍Giscus的配置流程，从GitHub仓库设置到Butterfly主题集成，让你轻松完成评论系统的配置。

🔹 1. 准备工作

在开始配置之前，请确保你已经准备好以下各项：

• ✅ 一个GitHub账号
• ✅ 一个公开的GitHub仓库（用于存储评论）
• ✅ 已安装并配置好的Hexo博客
• ✅ Butterfly主题（本教程基于Butterfly主题）

💡 建议：创建一个专门的GitHub仓库用于存储评论，这样可以更好地管理评论数据，避免与博客代码仓库混淆。

🔹 2. 配置GitHub仓库

步骤1：启用Discussions功能

1. 访问你的GitHub仓库
2. 点击仓库顶部的”Settings”（设置）选项卡
3. 向下滚动找到”Features”（功能）部分
4. 勾选”Discussions”（讨论）选项
5. 点击”Save changes”（保存更改）

📷 操作截图：

步骤2：安装Giscus GitHub应用

1. 访问Giscus GitHub应用页面
2. 点击”Install”（安装）按钮
3. 选择要安装Giscus的仓库
4. 点击”Install”（安装）完成安装

📷 操作截图：

🔹 3. 生成Giscus配置

1. 访问Giscus官方配置页面
2. 按照页面提示进行详细配置：

配置项	推荐设置	说明
仓库	username/repo	你的GitHub仓库地址
页面 ↔️ Discussion 映射	URL	推荐使用URL映射
Discussion 分类	Announcements	选择或创建一个分类
特性	根据需求勾选	建议勾选”启用反应”和”启用表情符号选择器”
主题	自动	选择与博客匹配的主题
语言	中文简体	选择评论系统的语言

📷 操作截图：

3. 配置完成后，页面会生成一段脚本代码，其中包含你的repo、repo-id、category-id等关键信息

✅ 配置完成：配置完成后，你会看到一段包含所有配置信息的脚本代码，稍后我们将使用这些信息配置Butterfly主题。

🔹 4. 配置Butterfly主题

在你的Hexo博客根目录下，找到themes/butterfly/_config.yml文件，进行以下配置：

步骤1：启用Giscus评论系统

comments:
  # 最多支持两个评论系统，第一个将作为默认评论系统
  # 选择: Disqus/Disqusjs/Livere/Gitalk/Valine/Waline/Utterances/Facebook Comments/Twikoo/Giscus/Remark42/Artalk
  use: [Giscus]
  # 在按钮旁边显示评论名称
  text: true
  # 懒加载: 当评论元素进入浏览器视口时才加载评论系统
  # 如果设置为 true，评论数量将无效
  lazyload: false
  # 在文章顶部图片显示评论数量
  count: true
  # 在首页显示评论数量
  card_post_count: true

📷 操作截图：

步骤2：配置Giscus详细参数

# Giscus评论系统配置
# https://giscus.app/
giscus:
  repo: your_username/your_repo  # 替换为你的GitHub仓库地址
  repo_id: your_repo_id  # 替换为你的仓库ID
  category_id: your_category_id  # 替换为你的分类ID
  light_theme: light  # 浅色主题
  dark_theme: dark  # 深色主题
  js: https://giscus.app/client.js
  option:
    # 交互功能配置
    reactionsEnabled: '1'  # 启用反应（👍 等）
    emitMetadata: '0'     # 不发送元数据
    inputPosition: top    # 评论框位置：top 或 bottom
    lang: zh-CN           # 语言设置
    loading: eager         # 加载方式：eager（立即加载）或 lazy（懒加载）
    # 安全与审核配置
    strict: '0'             # 严格模式：0（非严格）或 1（严格）
    mapping: url     # 映射方式：url、title、og:title、pathname等
    term: ''              # 自定义术语（仅在mapping为term时使用）
    backToTop: false      # 是否显示返回顶部按钮

📷 操作截图：

🔹 5. 获取Giscus配置参数

你可以从Giscus官方配置页面生成的脚本代码中提取以下关键参数：

• repo：GitHub仓库地址，如 username/repo
• repo-id：仓库ID，如 你的repo-id
• category-id：分类ID，如 你的category-id

例如，从以下脚本中提取：

<script src="https://giscus.app/client.js"
        data-repo="username/repo"
        data-repo-id="你的repo-id"
        data-category="Announcements"
        data-category-id="你的category-id"
        data-mapping="url"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="top"
        data-theme="light"
        data-lang="zh-CN"
        data-loading="eager"
        crossorigin="anonymous"
        async>
</script>

🔹 6. 启用评论功能

方式1：单篇文章启用

在文章的Front-matter中添加comments: true即可启用评论：

title: 文章标题
date: 2026-01-20 10:00:00
categories: 技术教程
tags: [Hexo, Giscus]
comments: true  # 启用评论

方式2：全局默认启用

在Hexo根目录的_config.yml中添加以下配置，为所有文章默认启用评论：

# 默认文章元数据设置
default_front_matter:
  comments: true # 默认启用评论功能

✅ 配置完成：现在你已经成功配置了Giscus评论系统，运行hexo s本地预览或hexo g -d部署到线上，即可看到评论系统已经生效。

🎨 Giscus高级配置

🔹 1. 自定义主题样式

Giscus支持自定义主题，你可以根据自己的博客主题调整Giscus的样式，使其与博客风格更加统一。

步骤1：创建自定义CSS样式

在source/css/custom.css文件中添加以下CSS代码，根据你的博客主题进行调整：

/* Giscus评论系统样式自定义 */

/* 评论区容器 */
giscus-widget {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
  border-radius: 8px;
  overflow: hidden;
}

/* 评论输入框 */
.gsc-input-box {
  border-radius: 8px !important;
  border: 1px solid var(--border-color) !important;
  background-color: var(--card-bg) !important;
  transition: all 0.3s ease !important;
}

.gsc-input-box:focus-within {
  border-color: var(--theme-color) !important;
  box-shadow: 0 0 0 2px rgba(102, 126, 234, 0.2) !important;
}

/* 评论按钮 */
.gsc-reply-button {
  background-color: var(--theme-color) !important;
  border-color: var(--theme-color) !important;
  border-radius: 8px !important;
  font-weight: 500 !important;
  transition: all 0.3s ease !important;
}

.gsc-reply-button:hover {
  background-color: var(--btn-hover-color) !important;
  border-color: var(--btn-hover-color) !important;
  transform: translateY(-1px) !important;
  box-shadow: 0 4px 12px rgba(102, 126, 234, 0.3) !important;
}

/* 评论头像 */
.gsc-avatar-image {
  border-radius: 50% !important;
  border: 2px solid var(--theme-color) !important;
  transition: all 0.3s ease !important;
}

.gsc-avatar-image:hover {
  transform: scale(1.1) !important;
  box-shadow: 0 2px 8px rgba(102, 126, 234, 0.4) !important;
}

/* 评论卡片 */
.gsc-comment {
  border-radius: 8px !important;
  border: 1px solid var(--border-color) !important;
  background-color: var(--card-bg) !important;
  transition: all 0.3s ease !important;
}

.gsc-comment:hover {
  transform: translateY(-2px) !important;
  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.1) !important;
}

/* 评论作者名称 */
.gsc-comment-author {
  color: var(--theme-color) !important;
  font-weight: 600 !important;
}

/* 评论时间 */
.gsc-comment-time {
  color: var(--text-light) !important;
  font-size: 0.85rem !important;
}

/* 反应按钮 */
.gsc-reactions {
  margin-top: 8px !important;
}

.gsc-reaction {
  transition: all 0.2s ease !important;
}

.gsc-reaction:hover {
  transform: scale(1.2) !important;
}

/* 深色主题适配 */
[data-theme="dark"] .gsc-comment {
  background-color: var(--card-bg) !important;
  border-color: var(--border-color) !important;
}

[data-theme="dark"] .gsc-comment:hover {
  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.3) !important;
}

/* 加载状态 */
.gsc-loading {
  color: var(--theme-color) !important;
}

/* 分页按钮 */
.gsc-pagination-button {
  color: var(--theme-color) !important;
  border-color: var(--border-color) !important;
  transition: all 0.3s ease !important;
}

.gsc-pagination-button:hover {
  background-color: var(--theme-color) !important;
  color: white !important;
}

/* 错误提示 */
.gsc-error {
  background-color: rgba(255, 87, 87, 0.1) !important;
  border-color: rgba(255, 87, 87, 0.3) !important;
  color: var(--text-color) !important;
}

🔹 2. 配置评论审核

Giscus使用GitHub Discussions的审核功能，你可以在GitHub上配置评论审核：

1. 访问你的GitHub仓库
2. 点击仓库顶部的”Discussions”（讨论）选项卡
3. 点击右上角的”Settings”（设置）按钮
4. 向下滚动找到”Moderation”（审核）部分
5. 根据需要配置审核选项：
   • Require first-time contributors to be approved before starting a discussion：首次贡献者需要审核才能发起讨论
   • Enable auto-merge for pull requests：启用PR自动合并

⚠️ 重要：建议启用首次贡献者审核，有效防止垃圾评论。

💡 Giscus使用技巧

🔹 1. 如何管理评论？

你可以在GitHub仓库的Discussions中轻松管理所有评论：

1. 访问你的GitHub仓库
2. 点击仓库顶部的”Discussions”（讨论）选项卡
3. 在左侧菜单栏中选择”Comments”（评论）分类
4. 在这里你可以：
   • 查看所有评论
   • 编辑评论内容
   • 删除不当评论
   • 标记评论为已解决
   • 管理评论者权限

📷 操作截图：

🔹 2. 如何禁止特定用户评论？

如果需要禁止特定用户评论，你可以：

1. 在GitHub仓库的Discussions中找到该用户的评论
2. 点击评论右上角的”…”（更多）按钮
3. 选择”Block user”（屏蔽用户）
4. 确认屏蔽该用户

⚠️ 注意：屏蔽用户是针对整个GitHub账号的，会影响该用户在你所有仓库的活动。

🔹 3. 如何导出评论数据？

由于评论存储在GitHub Discussions中，你可以通过以下方式导出评论数据：

1. 使用GitHub API：编写脚本调用GitHub API导出评论数据
2. 使用第三方工具：如GitHub Discussions Exporter
3. 手动导出：对于少量评论，可以手动复制粘贴

🔹 4. 如何统计评论数量？

你可以通过以下方式统计评论数量：

1. GitHub Discussions界面：直接在Discussions中查看评论数量
2. 第三方分析工具：如Google Analytics或Matomo
3. 自定义脚本：编写脚本调用GitHub API统计评论

🔹 5. 如何在本地测试Giscus？

在本地预览时，Giscus可能无法正常工作，因为GitHub API可能会拒绝来自localhost的请求。你可以：

1. 使用GitHub Pages或其他方式部署到线上测试
2. 修改hosts文件，将localhost映射为域名
3. 使用Giscus的开发模式

🔹 6. 如何优化Giscus性能？

为了优化Giscus的性能，你可以：

• 启用懒加载（但会导致评论数量不显示）
• 使用CDN加速Giscus脚本
• 优化GitHub API调用
• 合理设置加载模式（eager/lazy）

💡 性能建议：对于访问量较大的博客，建议启用懒加载并优化GitHub API调用频率。

❗ 常见问题解决

🔹 1. Giscus评论不显示

问题描述：页面加载后，评论区域为空或显示错误信息

解决方案：

1. 检查配置参数：确保repo、repo-id、category-id等参数正确无误
2. 验证GitHub仓库权限：确保仓库是公开的，并且已启用Discussions功能
3. 检查Giscus应用安装：确保已在GitHub上安装了Giscus应用并授权给你的仓库
4. 查看浏览器控制台：按F12打开开发者工具，查看控制台是否有报错信息
5. 清除浏览器缓存：尝试清除浏览器缓存后重新加载页面
6. 检查GitHub API状态：访问GitHub Status查看是否有API故障

🔹 2. 评论显示”加载中”但一直不显示

问题描述：评论区域一直显示”加载中”，无法显示评论内容

解决方案：

1. 检查网络连接：确保你的网络连接正常
2. 调整loading配置：将loading设置为eager（立即加载）
3. 检查GitHub API限制：如果博客访问量很大，可能会触发GitHub API的速率限制
4. 检查CORS设置：确保你的网站允许跨域请求
5. 尝试使用代理：对于某些地区，可能需要使用代理才能访问GitHub API

🔹 3. 深色主题不生效

问题描述：切换到深色主题时，Giscus评论系统没有相应变化

解决方案：

1. 检查dark_theme配置：确保dark_theme设置正确（如dark、dark_dimmed等）
2. 检查博客主题切换：确保博客主题切换功能正常，能够正确设置data-theme属性
3. 手动刷新页面：有时候主题切换后需要手动刷新页面才能生效
4. 检查Giscus版本：确保使用的是最新版本的Giscus
5. 自定义主题样式：如果自动主题适配有问题，可以通过CSS自定义主题

🔹 4. 评论数量不显示

问题描述：文章顶部或首页不显示评论数量

解决方案：

1. 检查count配置：确保comments.count设置为true
2. 检查card_post_count配置：确保comments.card_post_count设置为true
3. 检查lazyload配置：如果lazyload设置为true，评论数量将无法显示
4. 检查博客主题：确保主题支持显示评论数量
5. 检查GitHub API权限：确保Giscus有读取Discussions的权限

🔹 5. 评论发送失败

问题描述：用户无法发送评论，显示发送失败

解决方案：

1. 检查GitHub登录状态：确保用户已正确登录GitHub
2. 检查网络连接：确保用户网络连接正常
3. 检查评论内容：确保评论内容符合GitHub的规定
4. 检查审核设置：确保评论没有被审核系统拦截
5. 检查GitHub API限制：用户可能触发了GitHub API的速率限制

🔹 6. Giscus加载缓慢

问题描述：Giscus加载时间较长，影响页面性能

解决方案：

1. 启用懒加载：将lazyload设置为true，延迟加载评论
2. 优化加载模式：根据实际情况选择eager或lazy加载模式
3. 使用CDN加速：确保Giscus脚本使用CDN加速
4. 减少API调用：优化Giscus配置，减少不必要的API调用
5. 启用缓存：合理设置浏览器缓存策略

📊 Giscus与其他评论系统对比

特性	Giscus	Valine	Gitalk	Utterances	Disqus
存储方式	GitHub Discussions	LeanCloud	GitHub Issues	GitHub Issues	Disqus服务器
需要服务器	❌ 否	❌ 否（依赖LeanCloud）	❌ 否	❌ 否	✅ 是
开源免费	✅ 是	✅ 是	✅ 是	✅ 是	❌ 部分功能付费
支持Markdown	✅ 是	✅ 是	✅ 是	✅ 是	✅ 是
GitHub登录	✅ 是	❌ 否（支持匿名）	✅ 是	✅ 是	✅ 支持多种登录
主题适配	✅ 自动	✅ 手动	✅ 手动	✅ 自动	✅ 自动
配置复杂度	⭐⭐⭐ 中等	⭐⭐ 简单	⭐⭐⭐⭐ 复杂	⭐⭐ 简单	⭐⭐⭐⭐ 复杂
功能丰富度	⭐⭐⭐⭐ 高	⭐⭐⭐ 中等	⭐⭐⭐ 中等	⭐⭐ 低	⭐⭐⭐⭐⭐ 极高
垃圾评论防护	✅ 是（GitHub审核）	⭐⭐⭐ 中等	✅ 是（GitHub权限）	✅ 是（GitHub权限）	⭐⭐⭐⭐⭐ 极高
数据安全	⭐⭐⭐⭐⭐ 高	⭐⭐ 中等	⭐⭐⭐⭐ 高	⭐⭐⭐⭐ 高	⭐⭐ 中等
国内访问速度	⭐⭐⭐ 一般	⭐⭐⭐⭐ 快	⭐⭐⭐ 一般	⭐⭐⭐ 一般	⭐⭐ 慢
评论延迟	⭐⭐⭐ 轻微延迟	⭐⭐⭐⭐ 快	⭐⭐⭐ 轻微延迟	⭐⭐⭐ 轻微延迟	⭐⭐⭐ 轻微延迟
移动端适配	✅ 完美	✅ 良好	✅ 良好	✅ 良好	✅ 完美
自定义样式	✅ 支持	✅ 支持	✅ 支持	✅ 有限支持	✅ 支持
评论导出	✅ 支持（API）	✅ 支持	✅ 支持（API）	✅ 支持（API）	✅ 支持

💡 选择建议：对于GitHub用户，Giscus是一个不错的选择，功能丰富且无需维护服务器；对于国内用户，Valine可能访问速度更快；对于需要高级功能的用户，Disqus是一个全功能选项。

🎊 总结

通过本教程，你已经成功配置了Giscus评论系统，现在你可以：

• ✅ 享受稳定可靠的评论系统
• ✅ 让用户使用GitHub账号轻松评论
• ✅ 在GitHub上方便地管理评论
• ✅ 享受自动主题适配
• ✅ 无需担心服务器维护和数据库备份

下一步建议

1. 测试评论功能：部署到线上后，测试评论功能是否正常工作
2. 优化样式：根据你的博客主题，进一步优化Giscus的样式
3. 配置审核机制：启用评论审核，防止垃圾评论
4. 监控评论：定期查看和管理评论
5. 备份评论：定期导出评论数据，防止数据丢失

未来展望

Giscus作为一个基于GitHub Discussions的评论系统，具有很大的发展潜力。随着GitHub Discussions的不断完善，Giscus的功能也会越来越强大。

⚠️ 重要提示：leancloud将在2027年1月12号停止服务，如果你目前使用的是LeanCloud相关的评论系统（如Valine），建议尽快迁移到其他评论系统，如Giscus。

📚 参考资料

以下是一些有用的参考资料，帮助你进一步了解和使用Giscus：

• Giscus官方文档 - 最权威的Giscus使用指南
• Giscus GitHub仓库 - 查看源代码和提交issue
• Butterfly主题文档 - Butterfly主题的详细配置说明
• Hexo官方文档 - Hexo的官方文档
• GitHub Discussions文档 - GitHub Discussions的使用指南

---

更新时间： 2026-01-20
作者： Jay

返回顶部