用 Giscus 与 GitHub Discussions 给博客加评论：架构取舍与上线记录

我想给博客文章增加一个能持续讨论的地方，但不想为评论另建用户系统、数据库和审核后台。最终选择了 Giscus：文章页嵌入评论区，评论和身份由 GitHub Discussions 承担。第一版覆盖已发布的 Technical 和 Trading 文章。

这是一种有边界的选择。读者需要 GitHub 账号才能参与，讨论也会公开留在 GitHub；换来的是网站自身不必保存评论或处理登录。

先决定谁拥有评论数据

自己开发评论系统能完全控制体验，却也意味着要长期维护认证、存储、反滥用、备份和安全。托管评论服务可以减少开发，但会引入新的服务、计费与数据模型。这个博客的早期技术读者大多已经使用 GitHub，因此我接受了 GitHub 登录门槛，把讨论交给现成的 Discussions。

把这次选型画成一张截至 2026 年 9 月的作者定性比较图，而非量化评分：横轴是站长的持续维护负担，纵轴是读者发表评论前的参与门槛。图中 Hyvor Talk 和 Remark42 都假设已开启访客评论；订阅费用与数据迁移条件需另行比较，不包含在坐标中。

这张图显示了我接受的交换：Giscus 降低了网站侧的维护，却要求读者使用 GitHub 账号。Hyvor Talk 支持访客评论，但会引入托管服务和订阅；Remark42 可启用匿名评论，但服务器和数据仍要自己维护。坐标只反映这个博客的取舍，不是产品排名。

评论存放在独立的公开仓库 chankay-discussions，不与网站源码混放。仓库开启 Discussions，Giscus GitHub App 只安装在这个仓库，新文章的讨论归入 Announcements 分类。审核、锁定和后续回复都在 GitHub 进行。Payload CMS 不保存评论正文或访客账号。基础设施维护少了，但阅读和管理回复的工作仍然存在。

仓库根目录的 giscus.json 只允许正式网站的域名嵌入，并把默认顺序设为从旧到新。按 Giscus 官方说明，允许的来源与页面 origin 精确比较。因此预览域名如果要加载评论，需要先显式加入允许列表。

用不变的文章 ID 绑定讨论

Giscus 可以按 URL、路径或标题找讨论，但这里三个值都可能变：同一篇文章有中英文路径，slug 可以调整，标题也有翻译。如果直接用它们作为标识，改名后可能找不到旧讨论，中英文还可能分裂成两个讨论串。

因此使用 Giscus 的 specific 映射，把 post:<Payload 文档 ID> 作为匹配词，并启用严格匹配。中英文版本共享同一个文档 ID，也就共享同一个讨论；评论组件的语言和页面文案仍随当前语言变化。将来迁移 CMS 时，保留文章 ID 会直接关系到旧评论能否继续匹配。

评论区并不是在文章发布时就创建一条空讨论。读者接近页面底部后，才发生下面的查找流程：

Giscus 会先搜索匹配的 Discussion，有人首次评论或表态时才创建它。此前，稳定的 post:<ID> 只是查找键，不对应一条空讨论。页面还提供到 GitHub Discussions 的搜索链接，供嵌入组件无法加载时使用。

CMS 控制显示，网站负责呈现

Payload 有全局 Giscus 配置，也有每篇文章的 commentsEnabled 开关。没有这个新字段的旧文章按开启处理。只有已发布文章、全局与单篇开关都允许，且配置有效时，服务端才渲染评论区。关掉某篇文章的开关只会隐藏嵌入，不会删除 GitHub 上已有的讨论。

最终实现的职责边界可以用一张图概括：

Payload 决定入口是否出现，Next.js 负责呈现，Giscus GitHub App 把嵌入区连到公开讨论。iframe 加载失败时，备用链接仍能让读者找到讨论。

页面中的标题、说明和备用链接由可复用的 UI 区块呈现；一个小型客户端组件挂载官方 @giscus/react，让 iframe 在读者滚动接近评论区时再加载，并跟随网站的中英文和深浅色主题。评论区位于文章阅读进度范围之外，继续滚动看回复不会改变正文进度。构建页面时也不需要向 Giscus 服务端发请求。

上线检查中，我确认了中英文页面使用同一个 post:<ID>，并检查了 GitHub 登录入口、移动端宽度以及 Technical 和 Trading 路由。这里验证的是组件加载和映射，没有发布测试评论。

上线时遇到的缓存问题

第一次部署后，CMS 的新配置已经正确，部分预渲染文章却还保留旧状态。原有的 CMS 回调需要共享配置才能主动通知网站失效缓存；另外 www 域名会以 301 跳到主域名，POST 经这个跳转变成 GET，缓存刷新接口返回 405。仅凭 CMS 保存成功，不能推断公开页面已经更新。

文章详情现在对文章数据和全局配置都设置了 60 秒刷新间隔，作为评论开关的兜底。这不是即时审核开关：缓存过期后的首次请求仍可能收到旧页面，同时触发 Next.js 后台再生成。实际检查时，我关闭再恢复全局开关，中英文页面都在没有手动清缓存的情况下自动隐藏并恢复了评论区。以后若配置主动刷新回调，应直接指向主域名。

适用范围

这套方案适合读者愿意用 GitHub 的小型技术博客。它依赖 GitHub Discussions 和 Giscus，公开讨论数据也不在自己的 CMS 中。若读者群扩大到大量不用 GitHub 的人，登录门槛就值得重新评估。当前的职责划分很明确：Payload 决定是否显示，网站负责呈现，GitHub 保存讨论并提供管理工具。