Hexo 博客添加 Gitalk 评论系统（避坑指南）

给博客加上评论功能，花了半小时排查一个低级错误 —— 把 OAuth App 当成了 GitHub App。记录一下完整流程，帮后来者避坑。

效果预览

现在每篇文章底部都有评论框，访客用 GitHub 账号登录即可评论。评论数据存储在 GitHub Issues 中，免费、稳定、可追溯。

前置条件

Hexo 博客（我用的 7.3.0）
Butterfly 主题（5.5.4）
一个 GitHub 账号
一个用来存评论的 Public 仓库

核心步骤

第一步：创建评论仓库

新建一个 GitHub 仓库专门存放评论数据：

1
2
3

仓库名：chen-blog-comments（任意）
权限：Public（必须公开，否则访客无法读取）
初始化：勾选 "Add a README file"

第二步：创建 OAuth App（⚠️ 关键）

注意：是 OAuth App，不是 GitHub App

访问 https://github.com/settings/applications/new

填写信息：

字段	内容
Application name	Gitalk for 博客（任意）
Homepage URL	https://你的博客域名
Authorization callback URL	https://你的博客域名

注意：

Callback URL 不要加 /callback 后缀
必须用 https，除非你是本地测试

创建后获取：

Client ID（公开）
Client Secret（保密，只显示一次）

第三步：配置 Butterfly 主题

修改 _config.butterfly.yml：

comments:
  use: gitalk
  lazyload: true
  count: true

gitalk:
  client_id: Ov23lixxxxxxxxxxxxx  # 你的 Client ID
  client_secret: xxxxxxxxxxxxxxxxx  # 你的 Client Secret
  repo: chen-blog-comments        # 评论仓库名
  owner: JavaArthur               # 你的 GitHub 用户名
  admin: JavaArthur               # 管理员用户名
  option:
    language: zh-CN
    distractionFreeMode: false

第四步：部署

1
2
3

git add _config.butterfly.yml
git commit -m "feat: 添加 Gitalk 评论系统"
git push origin main

等待 Vercel 自动部署完成。

第五步：初始化评论

首次访问博客时，Gitalk 需要初始化：

打开任意一篇文章
点击 “Login with GitHub”
授权 OAuth App 访问
系统会自动在评论仓库创建对应的 Issue

注意：必须用 admin 配置的用户登录才能初始化。

常见错误

1. Bad credentials (401)

原因：把 GitHub App 当成了 OAuth App

解决：

删除错误的 GitHub App
重新创建 OAuth App（https://github.com/settings/applications/new）
更新 Client ID 和 Secret

2. Not Found

原因：评论仓库不存在或设为 Private

解决：确保仓库存在且为 Public

3. 评论框不显示

原因：comments.use 未设为 gitalk

解决：检查 _config.butterfly.yml 中 comments.use: gitalk

4. 登录后白屏

原因：Callback URL 配置错误

解决：OAuth App 中的 Callback URL 必须与博客域名完全一致（包括 https）

进阶配置

多管理员

1 2	gitalk: admin: ['JavaArthur', 'friend-github-username']

自定义标签

gitalk:
  option:
    labels: ['blog-comment']
    perPage: 10

与 Dark Mode 同步

Butterfly 的暗黑模式切换时，Gitalk 不会自动跟随。需要自定义 JS：

// 在主题配置中添加
gitalk:
  option:
    theme: 'github-light'  // 或 'github-dark'

数据迁移

如果从其他评论系统迁移：

Disqus → Gitalk：用 disqus-to-github-issues 工具
Valine → Gitalk：导出 JSON 后脚本转换
手动迁移：复制粘贴到对应 Issue

替代方案

如果不适合用 Gitalk，还有其他选择：

方案	特点	适合场景
Giscus	基于 GitHub Discussions	仓库必须是 Public
Waline	自建服务端，数据可控	有数据库（Supabase/MySQL）
Twikoo	腾讯云开发，零维护	不想折腾服务器
Utterances	基于 GitHub Issues，更简单	只需要基础评论功能