Utterances · 基于 GitHub Issues 的轻量博客评论组件｜零后端部署与使用全指南

项目仓库： https://github.com/utterance/utterances

开源协议：开源免费 · 定位：用 GitHub Issues 承载博客评论的轻量组件 · 数据存储：GitHub Issues · 样式：Primer CSS（GitHub 同款） · 技术栈：Vanilla TypeScript

1 项目简介

Utterances 是一个基于 GitHub Issues 构建的轻量评论组件：把 GitHub Issues 用作博客、Wiki 等的评论存储。它开源、无追踪、无广告、永远免费，不锁定（所有数据存在 GitHub Issues 中），用 GitHub 自己的 Primer CSS 工具包样式化，支持暗色主题，纯 Vanilla TypeScript，无需下载字体 / JS 框架 / polyfill。

1.1 核心信息一览

1.2 适用场景

• 博客 / 文档站希望评论数据免费托管在自己的 GitHub 仓库，零后端、零数据库。
• 读者群体是 GitHub 用户，愿意用 GitHub 账号评论。

1.3 能力边界（官方口径）

• 加载时用 GitHub issue search API 按 url / pathname / title 查找与页面关联的 issue；找不到时，第一次有人评论由 utterances-bot 自动创建 issue。
• 评论者需通过 GitHub OAuth 授权 utterances app 代为发帖，或直接在 GitHub issue 上评论。

2 功能特性

• 零后端：评论数据全部存在 GitHub Issues。
• 无追踪无广告：永远免费。
• 无锁定：数据在你的 GitHub 仓库。
• GitHub 同款样式：Primer CSS，支持暗色主题。
• 轻量：Vanilla TypeScript，无框架负担。

3 官方界面预览

Utterances 评论框嵌入文章页，外观与 GitHub issue 评论区一致：头像、Markdown 评论、 reactions。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• 一个 GitHub 仓库（公开）用于承载评论 issues。
• 在该仓库安装 utterances GitHub App（授权 bot 访问）。

5.2 硬件建议

• 无需服务器；组件纯前端加载。

5.3 端口与资源

• 无；以 script 标签加载。

6 方式一：引入 script 组件（唯一方式）

在文章页引入 utterances 的 script，配置 repo、issue-term、theme 等：

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

7 方式二：从源码构建（可选）

从仓库源码构建自定义组件，适合二次开发。

8 配置项说明

• repo：承载评论的 GitHub 仓库。
• issue-term：页面与 issue 的关联方式（url / pathname / title）。
• theme：主题（github-light 等）。

9 常用运维命令

• 评论 moderation：直接在 GitHub 仓库的 issues 里管理。

10 常见故障排查

• 评论不显示：确认仓库已安装 utterances app、issue-term 配置正确。

11 风险与合规说明

• 许可证：开源免费。
• 数据边界：评论数据存于你自己的 GitHub 仓库，需遵守 GitHub 服务条款。
• 本文整理自官方 README，配置以官方站点最新说明为准；不包含 star 数等动态数据。