Gitalk 2.0 · 基于 GitHub Discussions / Issues 的评论组件｜零后端部署与使用全指南

项目仓库： https://github.com/gitalk/gitalk

开源协议：MIT · 定位：无后端、无数据库、无第三方代理的评论组件 · 存储：GitHub Discussions（默认）或 GitHub Issues · 包：@aifire/gitalk / @aifire/gitalk-react / @aifire/gitalk-vue · 部署 CLI：gitalk-deploy

1 项目简介

Gitalk 2.0 是一个由 GitHub Discussions（默认）或 GitHub Issues 承载的评论组件：无后端、无数据库、无第三方代理。它使用 GitHub App（而非 1.x 的 OAuth App），让 token endpoint 在不出浏览器密钥的前提下签发 installation token。

1.1 核心信息一览

1.2 适用场景

• 博客 / 文档站希望评论数据存于自己的 GitHub 仓库，零后端。
• 1.x 用户迁移到 2.0：评论仍在 Issues，传 backend: 'issues' 即可。

1.3 能力边界（官方口径）

• 静态页面无法独立完成 OAuth 交换（github.com/login/oauth/access_token 不发 CORS 头），必须自建 token endpoint。
• 未登录、未装 proxy/App 时匿名读走浏览器直连 REST，限制 60 次/小时/IP；装了 proxy 走 GraphQL，5000 次/小时。
• 会话 30 天，App 配置 token 过期时静默续期。

2 功能特性

• 无后端：评论数据全在 GitHub Discussions/Issues。
• 三端包：框架无关、React、Vue。
• CORS 安全：client secret 只在自建 token endpoint，不进浏览器。
• 11 种语言：从 1.x 继承。
• 迁移友好：1.x 老评论在 Issues，传 backend: 'issues' 即可继续读写。

3 官方界面预览

Gitalk 评论框嵌入文章页，外观与 GitHub issue 评论一致。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• 一个公开 GitHub 仓库，开启 Discussions。
• 创建 GitHub App、安装到该仓库，并按部署 CLI README 配置权限与回调 URL。

5.2 硬件建议

• token endpoint 可用 Cloudflare Workers / CloudBase / Node 自托管；无需自备数据库。

5.3 端口与资源

• 静态页加载评论组件；token endpoint 一个 HTTP 入口。

6 方式一：自建 token endpoint（推荐）

npx github:gitalk/deploy -c .env -t cloudflare
# CloudBase：-t cloudbase；也可 Node 自托管

7 方式二：引入组件

pnpm add @aifire/gitalk          # 框架无关
pnpm add @aifire/gitalk-react   # React
pnpm add @aifire/gitalk-vue     # Vue

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@aifire/gitalk@latest/dist/gitalk.css">
<script src="https://cdn.jsdelivr.net/npm/@aifire/gitalk@latest/dist/gitalk.js"></script>

<div id="gitalk-container"></div>
<script>
  const gitalk = new Gitalk({
    clientID: 'Iv1.xxxxxxxxxxxx',
    owner: 'octocat',
    repo: 'demo-repo',
    admin: ['octocat'],
    number: 42,
    proxy: 'https://my-niubi-gitalk.octocat.workers.dev'
  })
  gitalk.render('gitalk-container')
</script>

8 配置项说明

• clientID：GitHub App client id。
• owner / repo：承载评论的仓库。
• admin：可在首次访问时创建 thread 的用户。
• backend：'discussions'（默认）或 'issues'（1.x 迁移）。
• number：推荐传 discussion 编号，避免标题扫描。
• proxy：自建 token endpoint origin。

9 常用运维命令

• 本地开发：pnpm install && pnpm dev && pnpm test && pnpm build。

10 常见故障排查

• 匿名 60 次/小时：proxy 未生效或 App 未安装。
• 1.x 评论不显示：传 backend: 'issues'。

11 风险与合规说明

• 许可证：MIT。
• 本文整理自官方 README，配置以部署 CLI README 最新说明为准；不包含 star 数等动态数据。