1. 为什么你的博客需要一个评论系统如果你正在运营一个个人博客无论是技术分享、生活记录还是兴趣探讨你可能会发现单向的输出总感觉少了点什么。文章发布后就像把石头扔进了寂静的湖面你听不到回响不知道读者是赞同、反对还是产生了新的疑问。这种“失联”的状态正是博客缺乏互动性的直接体现。一个评论功能就是打破这种单向传播、连接你与读者的桥梁。它能让你的博客从“公告板”变成一个“社区”读者可以提问、讨论、分享见解甚至纠正你的错误这些反馈是内容创作者最宝贵的财富。过去为静态博客比如用 Hexo、Hugo、Jekyll 等工具搭建的添加评论功能是个挺麻烦的事。你需要自己搭建后端服务器、设计数据库、处理用户认证和垃圾评论过滤运维成本很高。后来出现了一些第三方托管服务如 Disqus它确实方便一键嵌入即可。但随之而来的问题也很明显加载速度慢、隐私追踪、广告植入以及对于国内用户不太友好的访问体验。有没有一种方案既能享受第三方托管的便利又足够轻量、快速、开源且尊重隐私呢答案是肯定的。Giscus就是这样一种现代解决方案。它利用 GitHub Discussions 作为评论的存储后端将你的博客评论区变成一个 GitHub 仓库的讨论区。这意味着评论数据完全由你自己掌控存储在 GitHub 上加载速度快因为利用了 GitHub 的 API 和 CDN并且天然支持 Markdown、代码高亮、反应Reactions和引用回复。更重要的是它完全免费无需服务器配置过程简单到令人惊讶。接下来我就带你一步步实现它整个过程真的只需要几分钟。2. Giscus 的工作原理与前置条件在动手之前我们花一分钟理解一下 Giscus 是如何工作的这能帮你更好地完成配置并在出现问题时知道从哪里排查。Giscus 本质上是一个客户端 JavaScript 小部件。当读者访问你的博客文章时这个小部件会被加载。它会根据当前页面的 URL 或你指定的唯一标识符去对应的 GitHub 仓库的 Discussions讨论区里找到或创建一条相关的讨论主题。所有的评论、回复都会以 GitHub Discussion 帖子的形式存在。小部件负责将这些讨论内容获取并渲染到你的页面上同时提供一个表单让用户通过 GitHub 授权发表新评论。要实现这个流程你需要满足几个核心前提条件请务必逐一核对2.1 必备的四个条件你的博客必须是公开可访问的Giscus 脚本需要能正确获取到当前页面的 URL。如果你的博客仅在本地localhost运行Giscus 将无法与 GitHub API 正确关联。拥有一个 GitHub 账号这是评论者发表评论和你自己管理评论的基础。博客源码托管在一个 GitHub 仓库中这是最关键的一步。Giscus 需要知道评论数据应该关联到哪个仓库。即使你的博客最终部署在 Vercel、Netlify、GitHub Pages 或其他平台只要源代码仓库在 GitHub 上即可。为仓库启用 GitHub Discussions 功能Discussion 功能默认可能是关闭的。访问你的博客仓库页面。点击顶部的Settings设置选项卡。在左侧菜单中找到General通用下的Features功能。确保Discussions复选框是被勾选上的。如果之前没开过勾选后页面可能会刷新你需要再次进入Settings来配置接下来的步骤。2.2 安装 Giscus App 并配置 DiscussionGiscus 需要以 GitHub App 的身份来访问你的仓库以执行创建和读取讨论的操作。安装 Giscus App访问 Giscus 的官方配置页面https://giscus.app/zh-CN。这个页面会引导你完成整个设置。在页面第一个部分 “Repository仓库” 下点击Install GitHub App链接。这会跳转到 GitHub 的 Giscus App 安装页面。在安装页面你可以选择将 App 安装到你的个人账户或者你所属的组织。然后你需要选择可以访问哪些仓库。为了安全起见建议只授予它访问你的博客仓库的权限而不是所有仓库。选择好后点击Install。配置 Discussion 分类安装完 App 后回到你的博客仓库的Settings页面。这次在左侧菜单找到General下的Discussions如果找不到可以试试在设置页顶部的搜索框输入 “Discussions”。点击Set up discussions或直接进入配置。你需要创建一个讨论分类Category。Giscus 默认会使用Announcements公告分类但我强烈建议你为评论单独创建一个分类例如命名为Comments或Blog Comments。创建分类时可以上传一个图标并写一段简单的描述比如“来自博客文章的读者评论”。这能让你的讨论区更清晰。完成以上步骤你的仓库就准备好了。接下来我们进入最核心的配置环节。3. 在 Giscus 官网生成你的专属嵌入代码Giscus 的配置页面设计得非常直观你只需要像填表单一样做出选择它就会实时生成对应的代码。我们一步步来看每个选项的含义和推荐设置。打开https://giscus.app/zh-CN页面分为几个部分第一部分Repository仓库GitHub 仓库通过下拉菜单选择你刚刚安装了 Giscus App 的博客仓库格式为你的用户名/仓库名。Discussion 分类选择你上一步创建的专门用于评论的分类例如Comments。这确保了博客评论不会和其他类型的讨论混在一起。第二部分Page ↔ Discussions Mapping页面与讨论映射这个部分决定了如何将你的每一篇博客文章映射到一个唯一的 GitHub Discussion 主题。这是核心配置。Discussion 搜索方式有几种选择URL最推荐、最通用的方式。它使用当前博客页面的完整 URL如https://yourblog.com/posts/hello-world作为唯一标识。只要你的文章有固定且唯一的链接这就非常可靠。Page title使用文章标题。但如果标题可能重复或改变就不太稳定。Page pathname使用 URL 的路径部分如/posts/hello-world。如果你的博客部署在子路径下如yourname.github.io/blog这个方式可能比URL更灵活。Page-specific ID和Page-specific number需要你在博客 front-matter 中手动指定 ID更灵活但稍显复杂。Page-specific term手动指定一个搜索词。建议对于绝大多数静态博客生成器Hexo, Hugo, Jekyll, VuePress, Docsify等使用URL或Page pathname即可。Discussion 搜索特性这里有一些高级选项通常保持默认即可。仅搜索标题如果开启Giscus 会严格匹配 Discussion 的标题。建议关闭让搜索更宽松。在 Discussion 标题中嵌入搜索词建议开启。这样 Giscus 在自动创建新讨论时会把搜索词如文章标题放进 Discussion 的标题里便于你在 GitHub 上管理。在 Discussion 正文中嵌入搜索词建议开启。它会在 Discussion 的第一条评论即主题帖里放入文章链接等信息。第三部分Features特性这里可以开启或关闭一些 UI 功能。反应建议开启。允许读者对评论和文章点赞、表达惊叹等。输入时评论预览建议开启。用户在输入评论时可以看到 Markdown 的实时渲染效果。懒加载强烈建议开启。这意味着 Giscus 组件不会阻塞页面加载只有当用户滚动到评论区附近时才会开始加载极大提升页面首屏速度。使用明亮/黑暗主题可以根据你博客的主题进行切换。更推荐使用根据系统主题自动切换或者通过 CSS 变量在博客主题中自定义这样体验更统一。第四部分主题下拉菜单里有很多 GitHub 风格的主题可选如light,dark,dark_dimmed,transparent_dark等。选择一个和你博客设计最搭配的。这里的选择会体现在生成的脚本代码的>script srchttps://giscus.app/client.js >!-- 文章内容渲染区域 -- div classpost-content {{ post.content }} /div !-- Giscus 评论容器 -- div idgiscus-container/div !-- Giscus 脚本 -- script srchttps://giscus.app/client.js >/* 在你的博客CSS文件中 */ media (prefers-color-scheme: dark) { /* 覆盖 Giscus 深色主题变量 */ .giscus, .giscus-frame { --color-prettylights-syntax-comment: #8b949e; --color-prettylights-syntax-constant: #79c0ff; --color-canvas-default: #0d1117 !important; /* 背景色 */ --color-text-primary: #c9d1d9 !important; /* 主要文字色 */ --color-border-default: #30363d; /* 边框色 */ } }你可以通过浏览器开发者工具检查 Giscus 渲染出的元素查看它使用了哪些 CSS 变量然后有针对性地进行覆盖。Giscus 官方文档也列出了所有可用的主题变量。5.2 处理多语言和初始化状态语言脚本中的>link relpreconnect hrefhttps://giscus.app link relpreconnect hrefhttps://github.com自定义容器明确使用>