Skill · 评论系统（giscus） · sbraveyoung

Skill · 评论系统（giscus）

何时用：要打开评论 / 要换评论的承载仓库 / 要排查"评论框为啥没出现"。

解决什么：把 giscus 集成的全部配置点收拢到一处，开关单一，配置可逆。

为什么是 giscus

评论存在 GitHub Discussions 里，自己不用搭服务。
评论者必须 GitHub 登录，天然反垃圾。
数据完全归你（GitHub repo 的 Discussions 你随时可以导出）。
切回去 / 关掉，改一个布尔值，没有迁移成本。

启用步骤

新建一个公开 GitHub repo 专门放评论，比如 sbraveyoung/blog-comments。也可以复用 sbraveyoung/blog，但分开更干净——评论 issue / discussion 不会污染内容仓库的活动流。
在 repo settings 里开 Discussions：Settings → Features → ✅ Discussions。
去 https://giscus.app 跑一遍配置向导。它会让你填 repo + 选 Discussion 分类（一般选 "Announcements" 或自建一个 "Comments" 分类，权限设为只允许仓库 owner 创建新讨论），然后吐出四个 ID：
- Repo: sbraveyoung/blog-comments
- Repo ID: R_kgDOxxxxx
- Category: Announcements
- Category ID: DIC_kwDOxxxxx
在 sbraveyoung/blog-comments repo 上安装 giscus app：app 需要对那个 repo 的 Discussions 有写权限。

编辑 sbraveyoung.github.io/_gobog.json：

{
  ...
  "comments": {
    "enabled": true,
    "provider": "giscus",
    "repo": "sbraveyoung/blog-comments",
    "repo_id": "R_kgDOxxxxx",
    "category": "Announcements",
    "category_id": "DIC_kwDOxxxxx",
    "mapping": "pathname",
    "reactions_enabled": "1",
    "input_position": "bottom"
  }
}

commit + push。下次 deploy 跑完，所有 post 页面底部就有评论框了。

关掉

把 enabled 改成 false，commit + push。简单粗暴的开关。也可以临时手动跑一次 Deploy 来快速生效（不用等下次 push）。

那些字段都什么意思

字段	取值	意义
`enabled`	`true / false`	总开关。
`provider`	`giscus`	目前只支持 giscus；保留这个字段以后可以扩展到 utterances 等。
`repo`	`owner/name`	评论承载的仓库。
`repo_id`	`R_kgDOxxxxx`	giscus.app 给的不透明 ID，不是 repo 数字 id。
`category`	discussion 分类名	显示用。
`category_id`	`DIC_kwxxxxx`	同上，giscus.app 给的不透明 ID。
`mapping`	`pathname` / `url` / `title` / `og:title`	用什么把 post 跟 discussion 对上号。`pathname` 最稳。
`reactions_enabled`	`"1"` / `"0"`	显示 emoji 反应。
`input_position`	`top` / `bottom`	输入框在评论列表上面 or 下面。

评论系统在哪些页面出现

所有 post 页（/post/...）和顶层 page（/about 等用 post.html 模板的）会渲染评论。
列表页（首页、group 着陆页、tag 页、search 页）不会——它们用的是 index.html / group.html 模板。

主题切换

giscus iframe 内部用 data-theme="preferred_color_scheme" 跟随系统浅色 / 深色。这意味着用户手动切换主题（点 ☀ / ☾ 按钮）暂时不会同步到评论框——评论框跟着 OS 走。

下一步可以做的：JS 侧监听 theme toggle 事件，给 giscus iframe postMessage。短期内不做，因为大多数人就让浏览器跟系统走，体感差距很小。

排查

评论框完全没出现：检查 deploy workflow 跑没跑成功；如果跑成功了但页面上没有，hard refresh（CDN 缓存）；还是没出来去看页面源码搜 giscus.app/client.js，看 script 标签到底有没有渲染出来。
加载圈一直转：八成是 repo_id / category_id 填错了，去 giscus.app 重新跑一遍向导核对。
报 "discussion not found"：mapping 设成了 pathname 但 URL 是新的，giscus 会自动新建 discussion——前提是 giscus app 在 repo 上有写权限（前面第 4 步）。