Published on

在博客里开通 Giscus 评论的笔记

Authors
  • avatar
    Name
    Terry
    Twitter

我向来主张“把复杂的事讲简单”。Giscus 是基于 GitHub Discussions 的评论系统，逻辑并不复杂，只要几步就能跑起来。整篇文章分成两部分：先把 Giscus 在仓库里准备好，再去 Vercel 填环境变量。

第一部分：启动 Giscus

第一件事永远是确认前提条件，别在错误的起点上浪费时间。

  1. 仓库必须公开。Giscus 的讨论内容来自 GitHub Discussions，仓库如果设成私有，访客根本看不到讨论列表。确认仓库的 Visibility 为 Public，否则直接去改。
  2. 打开 Discussions 功能。进入仓库的 “Settings → General”，在 “Features” 里勾上 “Discussions”。没有这个入口，后面就没有讨论区可以承载评论。
  3. 安装 giscus GitHub App。访问 GitHub Apps - giscus，点击 “Install”，把它装到刚才的公开仓库里。没有 App 的授权，访客无法发表或同步评论。
  4. 在 giscus.app 生成配置。打开 https://giscus.app/zh-CN，选择 “GitHub Discussions” 作为后端，填入仓库的 owner/repo。页面会自动检查上面三个条件是否满足。

页面下方有个配置向导，按照顺序操作即可：

  • 选择 Discussions 的分类（一般用 General 或单独建个 Comments）。
  • 勾选 Enable reactions、Enable metadata 等偏好设置，保持默认即可。
  • 复制页面底部生成的配置信息：其中的仓库、repositoryId、category、categoryId 都是后面环境变量要用的值。

这一步就到此为止。本地不用写死这些 ID，放进环境变量才是干净的做法。

第二部分：在 Vercel 设置环境变量

Next.js 博客已经把 Giscus 的配置写成 process.env.* 的形式了，只要补齐变量即可。到 Vercel 的项目控制台里，依次添加下面这四个值，类型都选 “Environment Variable” 并作用在 Production 与 Preview：

NEXT_PUBLIC_GISCUS_REPO=your-name/your-repo
NEXT_PUBLIC_GISCUS_REPOSITORY_ID=从 giscus.app 复制的 repositoryId
NEXT_PUBLIC_GISCUS_CATEGORY=你挑选的 Discussions 分类名称
NEXT_PUBLIC_GISCUS_CATEGORY_ID=从 giscus.app 复制的 categoryId

我习惯在本地 /.env.local 里也放一份同样的键值，方便开发模式调试，用完别提交仓库。

环境变量填好以后，回到 Vercel 按下 Redeploy。部署完成后刷新博客文章页，评论区应该就会显示 Giscus 的 iframe。如果没有出现，先在浏览器控制台里看是否缺失变量，再确认仓库里的 Discussions 是否创建成功。

整个过程就是这么简单：先把 GitHub 的基础设施搭好，再在 Vercel 上补齐配置。没有多余的技巧，也没有神秘的黑魔法，只要按顺序走，评论区就能稳稳当当地上线。

Discuss on Twitter • View on GitHub