如何使用utterances给静态博客实现评论功能

# 如何使用utterances给静态博客实现评论功能

![utterances-logo](https://utteranc.es/logo.svg)

## 前言

对于静态博客（如Hexo、Hugo、Jekyll等）来说，实现评论功能一直是个挑战。传统的解决方案如Disqus虽然功能强大，但存在加载速度慢、隐私问题以及广告干扰等缺点。utterances则是一个基于GitHub Issues的轻量级评论系统，完美解决了这些问题。

本文将详细介绍如何为静态博客集成utterances评论系统，涵盖从原理到实现的完整流程。

---

## 一、utterances简介

### 1.1 什么是utterances

utterances是一个基于GitHub Issues的开源评论系统，具有以下核心特点：

- **完全免费**：无任何付费功能或限制
- **无广告**：不像Disqus那样植入广告
- **隐私友好**：不跟踪用户数据
- **Markdown支持**：评论支持GitHub风格的Markdown
- **自动同步**：评论与GitHub Issues实时同步

### 1.2 工作原理

1. 访客发表评论时，utterances会在你指定的GitHub仓库创建对应的Issue
2. 评论内容以Issue形式存储在你的仓库中
3. 页面加载时，utterances通过GitHub API拉取对应Issue的评论

![工作原理图](https://utteranc.es/client.png)

---

## 二、前期准备

### 2.1 必要条件

1. **GitHub账号**：用于管理评论
2. **公开的GitHub仓库**：存放评论数据
3. **静态博客网站**：已部署并可访问

### 2.2 创建专用仓库

建议专门创建一个仓库存放评论，例如：
- 仓库名：`blog-comments`
- 必须设置为**Public**（私有仓库无法使用）
- 初始化时可选添加README文件

---

## 三、安装utterances应用

### 3.1 授权utterances

1. 访问 [utterances应用页面](https://github.com/apps/utterances)
2. 点击"Install"按钮
3. 选择**特定仓库**或**所有仓库**（建议选择专用仓库）

![安装流程](https://i.imgur.com/xyz1234.png)

### 3.2 配置权限

确保应用有以下权限：
- Read/Write access to Issues
- Read access to metadata

---

## 四、生成嵌入代码

utterances提供配置工具自动生成嵌入代码：

1. 访问 [utterances配置页面](https://utteranc.es/)
2. 填写以下参数：

```html
<script 
  src="https://utteranc.es/client.js"
  repo="[你的GitHub用户名]/[仓库名]"
  issue-term="pathname"
  theme="github-light"
  crossorigin="anonymous"
  async>
</script>

4.1 参数详解

五、集成到静态博客

5.1 通用HTML集成

直接将生成的代码插入到你的模板文件中：

<!-- 评论容器 -->
<div class="comments">
  <script src="https://utteranc.es/client.js"
    repo="yourname/yourrepo"
    issue-term="pathname"
    theme="github-light"
    crossorigin="anonymous"
    async>
  </script>
</div>

5.2 常见静态博客集成示例

Hexo集成

编辑主题的_partial/comments.ejs文件：

<% if (theme.comments && theme.comments.utterances) { %>
  <div id="comments">
    <script 
      src="https://utteranc.es/client.js"
      repo="<%= theme.comments.utterances.repo %>"
      issue-term="<%= theme.comments.utterances.issue_term %>"
      theme="<%= theme.comments.utterances.theme %>"
      crossorigin="anonymous"
      async>
    </script>
  </div>
<% } %>

Hugo集成

在layouts/partials/comments.html中添加：

{{ if .Site.Params.utterances.enable }}
  <div id="utterances-comments"></div>
  <script src="https://utteranc.es/client.js"
    repo="{{ .Site.Params.utterances.repo }}"
    issue-term="{{ .Site.Params.utterances.issueTerm }}"
    theme="{{ .Site.Params.utterances.theme }}"
    crossorigin="anonymous"
    async>
  </script>
{{ end }}

六、高级配置技巧

6.1 自定义样式

通过CSS覆盖默认样式：

.utterances {
  max-width: 100%;
  margin: 0 auto;
}

.utterances-frame {
  background: transparent;
}

6.2 多语言支持

在配置中添加语言参数：

<script>
  document.addEventListener('DOMContentLoaded', function() {
    var script = document.createElement('script');
    script.src = 'https://utteranc.es/client.js';
    script.setAttribute('repo', 'yourname/yourrepo');
    script.setAttribute('issue-term', 'pathname');
    script.setAttribute('theme', 'github-light');
    script.setAttribute('crossorigin', 'anonymous');
    script.setAttribute('async', '');
    script.setAttribute('label', 'comments');
    document.getElementById('comments').appendChild(script);
  });
</script>

6.3 自动创建Issue

首次访问页面时，utterances会自动创建Issue。你也可以手动初始化：

1. 在GitHub仓库中新建Issue
2. 标题格式与issue-term设置匹配
3. 添加指定的label（如果有设置）

七、常见问题解答

Q1: 评论不显示怎么办？

• 检查仓库是否为Public
• 确认utterances应用已安装
• 查看浏览器控制台是否有错误

Q2: 如何迁移现有评论？

1. 将旧评论导出为Markdown
2. 在GitHub仓库中创建对应Issue
3. 粘贴评论内容

Q3: 如何防止垃圾评论？

• 启用GitHub仓库的Issue审核功能
• 设置label参数过滤非认证用户

八、替代方案对比

结语

utterances为静态博客提供了一种优雅的评论解决方案，结合GitHub的强大功能，既保证了数据自主权，又实现了良好的用户体验。本文详细介绍了从安装到配置的全过程，希望能帮助你轻松实现博客评论功能。

立即尝试utterances，让你的静态博客”活”起来！

最后更新：2023年10月 | utterances官网 “`

这篇文章包含了约1800字的内容，采用Markdown格式编写，包含： 1. 结构化标题 2. 图文并茂的说明 3. 代码块示例 4. 表格对比 5. 常见问题解答 6. 不同静态博客平台的集成方案

你可以根据需要调整内容细节或添加更多平台的具体集成方法。