Hugo 添加 Giscus 评论保姆级教程（基于 Bearblog 主题）

这篇文章手把手带你在 Hugo 博客里集成 Giscus（基于 GitHub Discussions 的评论系统）。

适用对象：使用 hugo-bearblog 主题或任意支持 layouts/partials/custom_body.html 扩展点的主题。

一、准备工作（一次性）

打开 https://giscus.app/zh-CN 并使用 GitHub 登录。
安装 “giscus” GitHub App 到你的仓库（例如 xin0712/logxin.cc）。
在仓库启用 Discussions：

仓库 → Settings → General → Features → 勾选 “Discussions”。
仓库顶栏进入 “Discussions”，新建一个分类（推荐 “Q&A” 或 “Comments”）。

回到 giscus.app 页面：

仓库填 xin0712/logxin.cc，映射方式选 pathname。
分类选择刚创建的 “Q&A”。
语言选中文，主题按需（建议 preferred_color_scheme）。
页面底部会生成一段 <script>，包含 repoId、category、categoryId 等参数。

示例（请以你在 giscus.app 实际生成的为准）：

 1<script src="https://giscus.app/client.js"
 2        data-repo="XXX"
 3        data-repo-id="XXX"
 4        data-category="Q&A"
 5        data-category-id="XXX"
 6        data-mapping="pathname"
 7        data-strict="0"
 8        data-reactions-enabled="1"
 9        data-emit-metadata="1"
10        data-input-position="top"
11        data-theme="preferred_color_scheme"
12        data-lang="zh-CN"
13        data-loading="lazy"
14        crossorigin="anonymous"
15        async>
16</script>

二、在 Hugo 配置中写入 Giscus 参数

在站点配置 hugo.toml 增加：

 1[params.giscus]
 2repo = "XXXX"
 3repoId = "XXXX"
 4category = "Q&A"
 5categoryId = "XXXX"
 6mapping = "pathname"
 7strict = 0
 8reactionsEnabled = 1
 9emitMetadata = 1
10inputPosition = "top"
11theme = "preferred_color_scheme"
12lang = "zh-CN"
13loading = "lazy"

三、在主题模板中挂载评论脚本

大多数主题都在 layouts/_default/baseof.html 里通过 {{ partial "custom_body.html" . }} 预留扩展位。创建（或覆盖）文件：

layouts/partials/custom_body.html

 1{{- $isSingle := eq .Kind "page" -}}
 2{{- $commentsOff := or (eq .Params.comments false) (eq .Site.Params.comments false) -}}
 3{{- if and $isSingle (not $commentsOff) -}}
 4  <script src="https://giscus.app/client.js"
 5          data-repo="{{ .Site.Params.giscus.repo }}"
 6          data-repo-id="{{ .Site.Params.giscus.repoId }}"
 7          data-category="{{ .Site.Params.giscus.category }}"
 8          data-category-id="{{ .Site.Params.giscus.categoryId }}"
 9          data-mapping="{{ .Site.Params.giscus.mapping }}"
10          data-strict="{{ .Site.Params.giscus.strict }}"
11          data-reactions-enabled="{{ .Site.Params.giscus.reactionsEnabled }}"
12          data-emit-metadata="{{ .Site.Params.giscus.emitMetadata }}"
13          data-input-position="{{ .Site.Params.giscus.inputPosition }}"
14          data-theme="{{ .Site.Params.giscus.theme }}"
15          data-lang="{{ .Site.Params.giscus.lang }}"
16          data-loading="{{ .Site.Params.giscus.loading }}"
17          crossorigin="anonymous"
18          async>
19  </script>
20  <noscript>请启用 JavaScript 以查看评论</noscript>
21{{- end -}}

说明：

仅在文章页（.Kind == "page"）渲染评论。
可以在某篇文章前言里用 comments = false 关闭评论。

四、构建与部署

本地构建：

1hugo --cleanDestinationDir

部署（示例脚本，SSH 走 443 端口，绕过代理）：

1bash ./deploy.sh

等待 GitHub Pages/CDN 生效（数十秒到数分钟），强制刷新浏览器查看。

五、可选性能优化

点击后再加载评论（推荐）：默认不注入脚本，点击“加载评论”按钮时再动态插入 <script>。
预连接域名（减少 TLS 时延），在 <head> 加入：

1<link rel="preconnect" href="https://giscus.app">
2<link rel="preconnect" href="https://github.com">
3<link rel="preconnect" href="https://api.github.com">
4<link rel="preconnect" href="https://avatars.githubusercontent.com">
5<link rel="dns-prefetch" href="https://giscus.app">
6<link rel="dns-prefetch" href="https://github.com">
7<link rel="dns-prefetch" href="https://api.github.com">
8<link rel="dns-prefetch" href="https://avatars.githubusercontent.com">

收敛请求：

1data-emit-metadata="0"
2data-reactions-enabled="0"

六、常见问题与排查

评论不显示：检查是否启用 Discussions、安装 giscus App、repoId/categoryId 是否正确。
首次加载慢：github.com/api.github.com/avatars.githubusercontent.com 等域名网络质量影响较大，可以采用“点击后加载评论”方案。
单篇文章关闭评论：前言加入 comments = false。

#Hugo #评论 #Giscus #教程