给 Astro 博客添加评论系统：用 Giscus 打通 GitHub Discussions

TL;DR

Giscus 是一个基于 GitHub Discussions 的评论系统，访客用 GitHub 账号发评论，评论内容存在你 GitHub 仓库的 Discussions 里。本文手把手教你在 Astro 博客接入 Giscus，从创建仓库到代码配置到样式定制。

前提：

博客托管在 GitHub（用于 Giscus 的 repo 授权）
GitHub 仓库开启了 Discussions 功能
访客需要登录 GitHub 才能评论（但不需要你授权）

Step 1：创建 GitHub 仓库（如果没有）

去 github.com/new 创建一个专门存放评论仓库，比如 blog-comments。设为 Public（Giscus 需要）。

Step 2：开启 Discussions

进入仓库 → Settings → General → Features → 勾选 Discussions。

这一步 Giscus 需要。没有 Discussions，Giscus 无法工作。

Step 3：安装 Giscus App

去 giscus.app 或在 GitHub Marketplace 搜索 giscus，安装到你博客仓库。

安装时设置：

Repository access：选择你博客仓库（gjcloak/Cloakblog）

Step 4：获取 repo ID

在 giscus.app 填入你仓库地址，它会告诉你 data-repo-id。

或者用 GitHub API 获取：

# 安装 gh CLI（如果没有）
brew install gh

# 登录
gh auth login

# 获取 repo ID
gh api graphql -f query='{repository(owner:"gjcloak", name:"Cloakblog"){id}}'

记下这个 ID，后面要用。

Step 5：在 Astro 中安装 Giscus

Astro 官方没有评论组件，需要自己写一个：

---
// src/components/Comments.astro
---
<section class="comments">
  <h2>评论</h2>
  <div class="giscus"></div>
</section>

<script is:inline>
  const giscusScript = document.createElement('script');
  giscusScript.src = 'https://giscus.app/client.js';
  giscusScript.setAttribute('data-repo', 'gjcloak/Cloakblog');
  giscusScript.setAttribute('data-repo-id', 'YOUR_REPO_ID');
  giscusScript.setAttribute('data-category', 'Announcements');
  giscusScript.setAttribute('data-category-id', 'YOUR_CATEGORY_ID');
  giscusScript.setAttribute('data-mapping', 'pathname');
  giscusScript.setAttribute('data-strict', '0');
  giscusScript.setAttribute('data-reactions-enabled', '1');
  giscusScript.setAttribute('data-emit-metadata', '0');
  giscusScript.setAttribute('data-input-position', 'bottom');
  giscusScript.setAttribute('data-theme', 'light');
  giscusScript.setAttribute('data-lang', 'zh-CN');
  giscusScript.setAttribute('data-loading', 'lazy');
  giscusScript.crossOrigin = 'anonymous';
  giscusScript.async = true;
  document.querySelector('.giscus').appendChild(giscusScript);
</script>

<style is:inline>
  .comments {
    margin-top: 48px;
    padding-top: 32px;
    border-top: 1px solid var(--border);
  }
  .comments h2 {
    font-size: 1.25rem;
    margin-bottom: 24px;
  }
</style>

注意替换：

data-repo：你的 GitHub 仓库（格式：用户名/仓库名）
data-repo-id：上一步获取 repo ID
data-category：Discussion 分类名称（一般用 Announcements）
data-lang：界面语言（zh-CN 或 en）

Step 6：接入文章页

在文章布局组件中引入：

---
// src/components/BlogPost.astro
import Comments from './Comments.astro';
---
<article>
  <h1>{title}</h1>
  <!-- 文章内容 -->
  <Comments />
</article>

Step 7：暗色模式适配

如果博客有暗色模式，需要让 Giscus 跟随主题切换：

// 在 script is:inline 中添加
function updateGiscusTheme() {
  const iframe = document.querySelector('iframe.giscus-frame');
  if (!iframe) return;
  const theme = document.documentElement.classList.contains('dark') 
    ? 'dark_dimmed' 
    : 'light';
  iframe.contentWindow.postMessage(
    { giscus: { setConfig: { theme } } },
    'https://giscus.app'
  );
}

// 监听主题切换
const observer = new MutationObserver(updateGiscusTheme);
observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] });

主题名称对应：

light / dark：官方主题
light_dimmed / dark_dimmed：低调版
transparent_dark / noborder_dark：透明/无边框

Step 8：自定义样式

Giscus 提供了部分 CSS 变量可以覆盖：

.giscus {
  --giscus-font-family: var(--font-body);
  --giscus-font-size: 16px;
}

但核心样式（iframe 内）无法从外部修改，这是 Giscus 的限制。如果需要完全自定义 UI，考虑 Utterances 或自建评论系统。

效果验证

部署后，打开任意一篇文章，滚动到底部应该能看到 Giscus 评论框。登录 GitHub 后可以发评论，评论会出现在仓库 Discussions 里。

Trade-offs

优点	代价
免费、无数据库	依赖 GitHub
访客需要 GitHub 账号	部分读者可能没有
评论数据存在你仓库	Discussions 会越来越多
隐私友好	Giscus 会请求 GitHub API

写在

Giscus 是目前最推荐博客评论方案之一：免费、维护简单、数据可控。如果你读者群体有 GitHub 账号，这是最优解。

没有 GitHub 账号的读者，可以考虑叠加 Utterances（基于 GitHub Issues，评论体验类似）。

延伸阅读

种下你的想法

在花园里留下一条评论，和这篇文章一起生长。

COMMENTS