这个站是 Hugo 生成的纯静态站点,托管在 GitHub Pages 上。没有服务器,也就没有地方存评论。想加评论区,绕不开一个问题:数据放在哪。

最后选了 giscus:评论存在 GitHub Discussions 里,前端只加载一个 iframe。这篇文章记录选型、接入过程,以及真正花时间的部分——让评论区和站点主题看起来像一家人。

一、静态站点为什么不能自己写评论

传统做法是「表单 → 后端 → 数据库」。GitHub Pages 只发文件,没有运行时,这条链路走不通。

可行的路线只剩三类:

  1. 第三方托管评论:Disqus、giscus、 utterances。
  2. 自建 Serverless 后端:Twikoo、Waline,前端 + 云函数 + 数据库。
  3. 不叫评论:邮件、Formspree 之类的留言表单。

Disqus 广告和追踪太多,国内访问也不稳定,先排除。Twikoo/Waline 能匿名留言,但要维护 Vercel、数据库和审核后台,对现在的需求偏重。

giscus 的取舍很明确:访客必须有 GitHub 账号,换来的是零后端、零数据库、无广告,评论天然归档在 Discussions 里。

二、giscus 的最小接入

先准备一个公开仓库专门放评论,例如 yicongl1/site-comments。源码仓库是私有的,不能拿来当评论仓库,否则 giscus 读不到。

步骤只有四步:

  1. 新建公开仓库;
  2. Settings → Features 勾选 Discussions;
  3. 新建分类,例如 Comments(类型选 Announcements 即可,讨论由 giscus App 创建);
  4. 安装 https://github.com/apps/giscus,授权到这个仓库。

然后在 https://giscus.app 填仓库,拿到两个 ID:

data-repo-id: "R_kgDO..."
data-category-id: "DIC_kwDO..."

Toha 主题本身带 giscus partial,把配置写进 hugo.yaml 就能用:

params:
  features:
    comment:
      enable: true
      services:
        giscus:
          repo: "yicongl1/site-comments"
          repoID: "R_kgDO..."
          category: "Announcements"
          categoryID: "DIC_kwDO..."
          theme: "preferred_color_scheme"
          map: "pathname"

这里有第一个坑:只有仓库名不够。repoID 和 categoryID 任何一个为空,giscus 都不会渲染。为了不让线上出现一个空框,我在自己的 comments.html 里加了判断,两个 ID 都存在才输出脚本。

三、评论应该出现在哪些页面

默认只给博客文章开。后来把项目页、代码页和首页也加上了,但不是所有页面都该有:

  • 博客文章:每篇一个讨论,map: pathname 自动按路径匹配;
  • 项目列表 / 项目详情:可以聊项目本身;
  • 代码学习页:每道题一个讨论,方便贴思路;
  • 首页:一个总留言板;
  • 私密空间:绝对不加。

最后一条是原则问题。私密页面的内容靠 Staticrypt 加密,如果在那里加载第三方 iframe,等于把「私密」的边界交给别人。评论区只出现在公开页面。

首页的留言区不是写死在模板里,而是作为一个普通 section 加进 data/*/sections/comments.yaml:

section:
  name: 留言
  id: comments
  enable: true
  weight: 99
  template: sections/comments.html

这样它会按权重排在首页最后,也不会挤进导航栏。

四、评论区的语言

giscus 的 data-lang 需要标准语言码。Hugo 这边 site.Language.Lang 是 zh-cn,giscus 认的是 zh-CN。不转换的话,界面会回退成英文。

所以 partial 里做了一次映射:

{{ $lang := $page.Site.Language.Lang }}
{{ if hasPrefix $lang "zh" }}{{ $lang = "zh-CN" }}
{{ else if hasPrefix $lang "fr" }}{{ $lang = "fr" }}{{ end }}

英语页直接用 en,法语页用 fr。中文站点的文章页是 zh-CN,评论区按钮和提示就都是中文了。

五、配色坑一:主题切换不跟手

theme: preferred_color_scheme 看起来最省事,但它跟的是操作系统,不是站点的明暗按钮。

站点右上角有手动切换。用户把站点切到深色、系统还是浅色时,评论区会固执地保持白色,非常突兀。

giscus 支持通过 postMessage 动态换主题:

function current() {
  return document.documentElement.getAttribute("data-theme") === "dark"
    ? "dark"
    : "light";
}

function sync() {
  const frame = document.querySelector("iframe.giscus-frame");
  if (!frame) return;
  frame.contentWindow.postMessage(
    { giscus: { setConfig: { theme: current() } } },
    "https://giscus.app"
  );
}

new MutationObserver(sync).observe(document.documentElement, {
  attributes: true,
  attributeFilter: ["data-theme"],
});

iframe 加载有时序,所以再加一个短轮询兜底:每 500ms 同步一次,10 秒后停止。这样无论是先加载 iframe 还是先切主题,最终都能对上。

六、配色坑二:首页多出一块矩形

博客页的评论区看起来很正常,首页却像贴了一块颜色不同的补丁。

原因是首页的每个栏目都包在 .section-holder 里,背景由主题在 bg-primary 和 bg-secondary 之间交替。giscus iframe 自己带固定底色:

  • 浅色主题 #ffffff
  • 深色主题 #0d1117

站点浅色背景是 #f8fafc,深色是 #1f2937。单独看都很接近,叠在一起就露馅。

试过给评论区加边框和卡片,反而更像补丁。最后的做法是:让包裹评论区的整条区块直接用 giscus 的底色,iframe 就融进去了。

.section-holder:has(> .comments-section) {
  background: #ffffff !important;
}

html[data-theme="dark"] .section-holder:has(> .comments-section) {
  background: #0d1117 !important;
}

:has() 在这里很好用:不用改主题的首页模板,也不用给每个 section 加特判,只命中「直接子元素是评论区」的那一条区块。博客页没有 .section-holder,完全不受影响。

七、配色坑三:代码区永远是深色

代码学习栏目一开始是写死的深色终端。浅色主题下,整页是浅色,中间突然一块黑,像另一个网站。

改法是把它变成一组 CSS 变量,在浅色和深色下各给一套值:

.code-terminal {
  --ct-bg: #f7f9fa;
  --ct-text: #22313a;
  --ct-accent: #248aaa;
}

html[data-theme="dark"] .code-terminal {
  --ct-bg: #0d151b;
  --ct-text: #d3e0e6;
  --ct-accent: #5bc0da;
}

浅色模式是纸白终端,深色模式保持暗色,强调色统一用站点的青蓝 #248aaa,而不是随便找一套 GitHub 配色。评论 iframe 也去掉固定的 dark_dimmed,跟着同一套主题走。

八、验证与日常维护

静态站点没有后端日志,改完只能靠构建产物和线上检查。我加了一个 scripts/check-site.ps1,每次发布后检查:

  • public/private 里每个页面都必须是 Staticrypt 加密页;
  • 博客、项目、代码页存在;
  • 首页的 GitHub/Gitee 热力图还在;
  • 代码页的终端样式还在。

评论本身没法在构建期验证「能不能发出去」,但可以确认:

  • 每类页面都有 giscus 脚本;
  • data-repo-id / data-category-id 正确;
  • 私密页没有加载任何第三方评论脚本。

发布后在线上抽查一遍,比在本地点 iframe 更可靠。

九、代价

giscus 不是没有成本:

  • 访客要有 GitHub 账号,非技术朋友可能直接放弃;
  • 评论公开在 GitHub 上,删改都要去 Discussions;
  • 依赖 giscus 服务和 GitHub 的可用性;
  • 评论内容是用户生成的,将来要考虑审核和垃圾信息。

如果以后需要匿名留言,可以保留 giscus 作为文章评论,另开一个 /guestbook/ 用 Twikoo。两者不冲突。

十、小结

这次真正的工作量不在「把 iframe 贴上去」,而在三件事:

  1. 范围:哪些页面该有评论,哪些页面绝对不能有;
  2. 语言:zh-cn 和 zh-CN 这种细节;
  3. 配色:让第三方 iframe 和站点主题看起来是同一个设计系统。

静态站点接评论,技术上是一个 iframe;体验上,是一整套边界和细节。