hugo@基于github issue评论系统utterances

Posted on Views:

Utterances 是一个基于 GitHub Issues 的评论系统，适用于静态博客等网站，特别适合使用 GitHub Pages 和 Markdown 博客的开发者（例如 Hugo、Jekyll、Hexo 等生成的站点）。

它使用 GitHub Issues 来存储评论，因此没有独立的后台服务或数据库依赖，只要你有一个公共的 GitHub 仓库，就可以免费使用。

🔧 1.功能简介

  • 评论存储在 GitHub Issues 中：每个页面的评论对应一个 issue。
  • 基于 OAuth 的登录机制：使用者需要通过 GitHub 账户登录进行评论。
  • 无广告、开源免费。
  • 支持多种“页面 ↔ Issue”关联方式：包括 pathname、url、title、og:title 等。
  • 样式简洁，自动适配 GitHub 风格和暗色主题。

🚀 2.如何使用 Utterances

1. 准备工作

  • 一个用于存储评论的公共 GitHub 仓库（如：your-username/blog-comments）。
  • 博客网站支持插入 JavaScript（大多数都支持）。

2. 安装 GitHub App

前往 https://github.com/apps/utterances：

  1. 点击右上角 “Install”。
  2. 选择你的账号或组织。
  3. 选择用于存储评论的 仓库。
  4. 授予该仓库权限（建议只授予你想用于评论的仓库）。

3. 页面嵌入代码

在你的网站页面中插入如下 HTML 代码：

1
2
3
4
5
6
7
8
<script src="https://utteranc.es/client.js"
        repo="your-username/blog-comments"
        issue-term="pathname"
        label="💬 comment"
        theme="github-light"
        crossorigin="anonymous"
        async>
</script>

各字段说明：

  • repo：用于存储评论的 GitHub 仓库。

  • issue-term：决定如何将页面与 issue 关联。

    • 可选项：pathname、url、title、og:title 等。

  • label：为生成的 issue 添加标签。

  • theme：支持多种主题，比如：

    • github-light、github-dark、preferred-color-scheme 等。

🎨 3.主题样式

支持的主题有：

  • github-light
  • github-dark
  • preferred-color-scheme（根据用户系统自动切换）
  • github-dark-orange
  • icy-dark
  • dark-blue
  • photon-dark

📝 4.页面与 Issue 的对应关系（issue-term）

这是 Utterances 最核心的功能之一，它根据你设定的 issue-term 来自动查找或创建对应的评论 issue。

例如：

1
issue-term="pathname"

那么 /post/my-blog 页面会关联到一个标题为 /post/my-blog 的 GitHub Issue。

如果没有找到对应的 issue，Utterances 会在首次加载该页面时创建一个新的 Issue。

🛠️ 5.常见问题

Q: 评论区无法加载？

  • 请确认 GitHub App 已正确安装并授权目标仓库。
  • 目标仓库必须为 公开仓库（私有仓库无法使用）。
  • 页面使用的是 HTTPS。
  • 检查浏览器控制台有无跨域错误或 CSP 限制。