Utterances教程：基于Github Issues的轻量级博客评论系统

主页传送门：📀 传送

前言

---

  最近刚用github pages 整好自己的博客。最开始用的是gitalk，不过它虽然同样基于 GitHub issues 的评论插件但是基于以下几点原因，因此仔细研究考虑了下决定改成换用Utterances。

• gitalk必须将 clientID 和 clientSecret 硬编码到配置里，而这个操作会将二者直接暴露出去。

• 尽管获得对 repos 的操作权限还需要授权 Token，但是这个可以通过反代 GitHub API 等手段拿到。由于 GitHub 在权限粒度上并没有进一步细分（也就是说不能只操作 issues），所以一旦拿到 Token，对方就可以删光你的 public repos，因此使用它们的风险是非常高的。

• 相较而言 Utterances 通过 GitHub App 实现，可以只对 issues 进行授权。

• Utterances 另一个好处就是不需要初始化，而 Gitalk 评论插件是需要作者自己手动初始化的。

简介

---

  本文主要介绍基于 GitHub issues的轻量级博客评论系统Utterances。
  Utterances是一个开源的评论系统，它利用GitHub Issues作为存储和处理评论的基础。
  这一系统因其轻量级的特性和易于集成的优点而被广泛使用于个人博客、文档和其他静态网站中。

  它具有以下特点：

• 开源
• 不追踪，无广告，始终免费
• 所有的数据都存储在Github Issues
• 样式基于Github的Primer设计语言
• 夜间模式
• 轻量级；原生TypeScript。
• 快速上手

优势：

• 轻量且强大：Utterances以其体积小巧、加载速度快而闻名，对页面性能的影响极小，同时还提供了丰富的功能如实时同步更新等。
• 安全可控：由于基于GitHub的安全机制，Utterances能有效防止垃圾评论和滥用行为。
• 社区参与度高：通过使用GitHub账号发表评论，Utterances鼓励用户参与社区讨论，增强了用户的归属感。
• 透明度高：所有的评论都是公开透明的，便于追溯和管理。
• 样式美观：Utterances使用Primer设计语言，这是Github官方使用并开源的设计指南，所以Utterances有和Github Issues类似的漂亮样式。

具体步骤

---

1. 首先保证自己的博客是 public 仓库，以便于存储评论数据。
2. 安装 Utterances 申请 GitHub App
   打开 utterances - GitHub App 点击 Install 进入安装页面。

在打开的页面中选择 Only select repositories，并在下拉框中选择自己的博客仓库（比如我就是 zccztt/zccztt.github.io，也可以安装到其他仓库），然后点击 Install。

选择博客文章和GitHub Issues之间的映射

• Issue标题包含页面路径名
  Utterances将查询issue标题是否包含博客文章的路径名（pathname）。如果未找到匹配的issue，则当有人首次对你的博客文章发表评论时，Utterances会自动创建一个以此文章路径名为标题的issue。
• Issue标题包含页面URL
  Utterances将查询issue标题是否包含博客文章的URL。如果未找到匹配的issue，则当有人首次对你的博客文章发表评论时，Utterances会自动创建一个以此文章URL为标题的issue。
• Issue标题包含页面标题
  Utterances将查询issue标题是否包含博客文章的标题。如果未找到匹配的issue，则当有人首次对你的博客文章发表评论时，Utterances会自动创建一个以此文章标题为标题的issue。
• Issue标题包含页面og:title
  Utterances将查询issue标题是否包含博客文章的Open Graph标题（og:title）。如果未找到匹配的issue，则当有人首次对你的博客文章发表评论时，Utterances会自动创建一个以此文章og:title为标题的issue。
• 特定的issue编号
  Utterances按issue编号加载特定的issue。Utterances不会自动创建issue。
• Issue标题包含特定项
  Utterances将查询issue标题是否包含你设置的特定项。如果未找到匹配的issue，则当有人首次对你的博客文章发表评论时，Utterances会自动创建一个以你设置的特定项为标题的issue。

将生成的这段copy到你需要用的地方即可。

在你的网页需要插入Utterances评论的位置，粘贴以下代码（username，reponame分别修改为你的GitHub用户名，仓库名）。

 <script src="https://utteranc.es/client.js"
         repo="username/reponame"
         issue-term="pathname"
         theme="github-light"
         crossorigin="anonymous"
         async>
 </script>

刷新网页就可以看到Utterances评论框了。
配置
主要介绍repo，issue-term，label，theme几个选项的配置。

• repo：设置存放评论的仓库。
  Utterances 使用Github Issues存储评论，所以需要一个仓库。你可以新建一个公开仓库专门用来放评论，也可以使用原有的仓库。要设置存放评论的仓库只需要将repo="username/reponame"这一行中的username改为你的GitHub用户名，reponame改为你的仓库名，其它不变。(仓库必须为公开仓库，私有仓库访客无法查看对应Issues上的评论 | 如果你的仓库是派生(fork)出的，请在仓库的Settings选项确认Features区Issues已勾选 。)

• issue-term: 博客文章和GitHub Issues之间的映射

  • Issue标题包含页面路径名（issue-term=“pathname”）
    Utterances将查询issue标题是否包含博客文章的路径名（pathname）。如果未找到匹配的issue，则当有人首次对你的博客文章发表评论时，Utterances会自动创建一个以此文章路径名为标题的issue。
  • Issue标题包含页面URL（issue-term=“url”）
    Utterances将查询issue标题是否包含博客文章的URL。如果未找到匹配的issue，则当有人首次对你的博客文章发表评论时，Utterances会自动创建一个以此文章URL为标题的issue。
  • Issue标题包含页面标题（issue-term=“title”）
    Utterances将查询issue标题是否包含博客文章的标题。如果未找到匹配的issue，则当有人首次对你的博客文章发表评论时，Utterances会自动创建一个以此文章标题为标题的issue。
  • Issue标题包含页面og:title（issue-term=“og:title”）
    Utterances将查询issue标题是否包含博客文章的Open Graph标题（og:title）。如果未找到匹配的issue，则当有人首次对你的博客文章发表评论时，Utterances会自动创建一个以此文章og:title为标题的issue。
  • 特定的issue编号（issue-number=“具体数字”）
    Utterances按issue编号加载特定的issue。Utterances不会自动创建issue。
  • Issue标题包含特定项（issue-term=“你设置的特定内容”）
    Utterances将查询issue标题是否包含你设置的特定项。如果未找到匹配的issue，则当有人首次对你的博客文章发表评论时，Utterances会自动创建一个以你设置的特定项为标题的issue。

• label：Issue标签

  • 如果你使用原有的仓库，但是担心Issues页面评论和问题混杂在一起，Utterances支持设置标签（Label）来区分它们。设置label=“你的标签内容”，Utterances将在创建issue时使用你设置的标签。

  • 标签名区分大小写。

  • 标签必须存在于你的仓库中（须提前在GitHub Issues页面创建好，不能使用不存在的标签）。

  • 标签名支持Emoji。例如：
    label=“💬”

• theme：主题
  Utterances有多种主题，其中包括多款夜间模式主题。

GitHub Light：theme="github-light"
GitHub Dark：theme="github-dark"
GitHub Dark Orange：theme="github-dark-orange"
Icy Dark：theme="icy-dark"
Dark Blue：theme="dark-blue"
Photon Dark：theme="photon-dark"

  如果喜欢的话，欢迎 🤞关注 👍点赞 💬评论 🤝收藏  🙌一起讨论
  你的支持就是我✍️创作的动力！					  💞💞💞