给静态博客接上评论区:giscus、主题同步与三个配色坑
这个站是 Hugo 生成的纯静态站点,托管在 GitHub Pages 上。没有服务器,也就没有地方存评论。想加评论区,绕不开一个问题:数据放在哪。
最后选了 giscus:评论存在 GitHub Discussions 里,前端只加载一个 iframe。这篇文章记录选型、接入过程,以及真正花时间的部分——让评论区和站点主题看起来像一家人。
一、静态站点为什么不能自己写评论
传统做法是「表单 → 后端 → 数据库」。GitHub Pages 只发文件,没有运行时,这条链路走不通。
可行的路线只剩三类:
- 第三方托管评论:Disqus、giscus、 utterances。
- 自建 Serverless 后端:Twikoo、Waline,前端 + 云函数 + 数据库。
- 不叫评论:邮件、Formspree 之类的留言表单。
Disqus 广告和追踪太多,国内访问也不稳定,先排除。Twikoo/Waline 能匿名留言,但要维护 Vercel、数据库和审核后台,对现在的需求偏重。
giscus 的取舍很明确:访客必须有 GitHub 账号,换来的是零后端、零数据库、无广告,评论天然归档在 Discussions 里。
二、giscus 的最小接入
先准备一个公开仓库专门放评论,例如 yicongl1/site-comments。源码仓库是私有的,不能拿来当评论仓库,否则 giscus 读不到。
步骤只有四步:
- 新建公开仓库;
- Settings → Features 勾选 Discussions;
- 新建分类,例如
Comments(类型选 Announcements 即可,讨论由 giscus App 创建); - 安装 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 贴上去」,而在三件事:
- 范围:哪些页面该有评论,哪些页面绝对不能有;
- 语言:
zh-cn和zh-CN这种细节; - 配色:让第三方 iframe 和站点主题看起来是同一个设计系统。
静态站点接评论,技术上是一个 iframe;体验上,是一整套边界和细节。
相关技能
- Hugo
- giscus
- GitHub Discussions
- CSS