评论系统怎么接入博客的

0
Hugo Giscus 评论 Disussions

博客不能没有评论. 但又不想为了一个评论功能去搞数据库和 moderation. Giscus 是一个折中方案.

这个博客的评论系统用的是 Giscus. 它基于 GitHub Discussions. 所有评论都直接存在 GitHub 仓库里, 不需要自建数据库, 不需要第三方服务.

整体流程

用户打开文章页
      ↓
加载 giscus.app/client.js
      ↓
Giscus 脚本读取 data- 属性配置
      ↓
根据 mapping="pathname" 取当前 URL 路径
      ↓
用 GitHub Discussions API 查询匹配的 Discussion
      ↓
找到 → 渲染评论框和已有评论
未找到 → 显示"留个评论吧"输入框
      ↓
用户写评论 → 点击发布
      ↓
跳转 GitHub OAuth 授权 (首次需要)
      ↓
评论通过 API 写入仓库的 Discussions
      ↓
Giscus WebSocket 监听变更 → 实时更新评论区

整个过程用户无感知, 不需要离开页面.

哪里对接

评论系统以 script 标签嵌入页面. 在 layouts/partials/comments.html 里:

<div class="blog-post-comments">
  <script src="https://giscus.app/client.js"
    data-repo="0x1428571429/time-friend.com"
    data-repo-id="MDEwOlJlcG9zaXRvcjoxNTQ0NDY1NTc="
    data-category="Announcements"
    data-category-id="DIC_kwDOCTSq3c4DB723"
    data-mapping="pathname"
    data-strict="0"
    data-reactions-enabled="1"
    data-emit-metadata="0"
    data-input-position="bottom"
    data-theme="noborder_dark"
    data-lang="{{ if eq .Lang "zh" }}zh-CN{{ else }}en{{ end }}"
    crossorigin="anonymous">
  </script>
</div>

数据对接地址是 GitHub 仓库 0x1428571429/time-friend.com. Giscus 脚本通过 GitHub 的 Discussions API 读写评论. 不需要自己配后端.

页面模板里引用这个 partial:

{{ partial "comments.html" . }}

文章页的 single.html 里在内容区下面直接引入就行.

参数详解

data-repo

评论存放的 GitHub 仓库. 0x1428571429/time-friend.com.

所有评论以 GitHub Discussions 的形式存在这个仓库里. 可以直接在 GitHub 上管理.

data-repo-id

仓库的 GitHub 内部 ID. MDEwOlJlcG9zaXRvcjoxNTQ0NDY1NTc=.

这个值是固定的, 在 Giscus 官网 (https://giscus.app) 输入仓库名后自动生成. 不需要自己查. 配置好就不用动.

data-category / data-category-id

Discussion 的分类. 用的 Announcements, 分类 ID DIC_kwDOCTSq3c4DB723.

设置步骤:

  1. 在 GitHub 仓库的 Settings > Features 里勾选 Discussions
  2. 进入仓库的 Discussions 标签页, 创建一个分类 (比如 Announcements)
  3. 在 Giscus 官网选择这个分类, 官网会自动生成 category-id

所有文章的评论都归到这个分类下, 方便管理.

补充一点: GitHub 仓库的 Discussions 功能不是默认开启的. 在 Settings > Features 里找到 Discussions, 打勾才会出现. 我当时配完 Giscus 发现不生效, 排查了半天, 最后发现是这里没开.

data-mapping

文章页和 Discussion 的映射方式. 我用的 pathname, 即当前页面 URL 路径.

比如用户访问 /zh/archive/blog-architecture-overview, Giscus 就用这个路径去匹配 Discussion 的标题或内容.

其他可选值:

  • title: 用页面标题匹配. 但如果改过标题, 以前的评论就丢了 → 不推荐
  • url: 用完整 URL 匹配. 但如果域名或协议变了也会丢
  • og:title: 用 Open Graph 的 title 匹配

pathname 最稳定. URL 路径不变就不会匹配错. 反过来, 如果你改了文章的 slug, 之前所有的评论就找不到了. 所以文章一旦发布, slug 不要轻易改. 吃过这个亏.

data-strict

是否严格匹配. 设为 0, 允许部分匹配, 容错性更好. 如果因为某些原因没能精确匹配, 也能找到相近的 Discussion.

data-theme

Giscus 的主题. noborder_dark 是无边框的暗色主题, 跟博客的整体风格一致.

Giscus 提供多套主题: light, dark, noborder_light, noborder_dark, preferred_color_scheme 等. 也可以自定义 CSS 主题.

data-lang

评论界面的语言. 根据当前页面语言动态切换:

zh-CN → 中文界面
en → 英文界面

Giscus 支持几十种语言.

其他

  • data-reactions-enabled="1": 启用表情反应, 读者可以给评论点赞
  • data-emit-metadata="0": 不发送元数据, 保护隐私
  • data-input-position="bottom": 评论输入框在评论区底部, 符合阅读习惯
  • crossorigin="anonymous": 跨域设置
  • async: 异步加载, 不阻塞页面渲染

数据怎么查

评论全部存在 GitHub 仓库的 Discussions 里. 访问:

https://github.com/0x1428571429/time-friend.com/discussions

可以直接在 GitHub 上:

  • 浏览评论: 按文章分类, 按时间排序
  • 管理评论: 删除垃圾评论, 编辑或置顶回复
  • 回复访客: 直接在 GitHub Discussions 里回复, 访客能看到
  • 批量操作: 关闭 Discussion, 转移分类, 标记为解答

每个文章页面对应一个 Discussion. Discussion 的标题默认是页面路径, 比如 /zh/archive/blog-architecture-overview. 在 GitHub 上一眼就能看出是哪篇文章的评论区.

Giscus 内部用的是 GitHub 的 GraphQL API. 查询时:

  1. 用 data-repo 定位仓库
  2. 用 data-mapping (pathname) 构建搜索条件
  3. 调 search 类型的 GraphQL 查询找匹配的 Discussion
  4. 找到就渲染, 没找到就显示空白评论区, 等用户第一次发布时自动创建

评论的高亮和代码块

Giscus 的评论框支持 Markdown 语法. 访客写评论时可以用:

**加粗**
`行内代码`

\```javascript
const code = "代码块";
\```

代码块会自动高亮, 跟博客文章的风格一致. 这对技术博客来说很重要, 访客在讨论技术问题时可以直接贴代码.

优缺点

好处

零运维. 不需要数据库, 不需要服务器, 不需要 moderation 后台. 评论数据存在自己的 GitHub 仓库里, 不会有"某个第三方服务突然关停"的问题.

数据自主. 评论就是仓库里的 Discussions, 可以随时导出, 迁移, 备份. 不像 Disqus 那样数据在人家手里.

访客体验好. 用 GitHub 账号登录, 不需要额外注册. OAuth 授权流程是 Giscus 处理的, 开发者一行代码都不用写.

实时更新. WebSocket 推送, 一个访客发布评论后, 其他正在看同一篇文章的人立刻就能看到.

反垃圾. GitHub 账号本身有注册门槛, 比起 Disqus 那种匿名评论, 垃圾评论少得多.

缺点

访客必须有 GitHub 账号. 非开发者用户可能没有. 但这个博客的读者基本都是开发者, 问题不大.

GitHub 在国内偶尔不稳定. Giscus 脚本从 giscus.app 加载, API 调的是 GitHub 的接口. 国内访问 GitHub 有时会慢甚至超时. 博客读者以海外为主, 可以接受.

文章链接：

/zh/archive/blog-architecture-giscus/

# 相关文章推荐