💬 Giscus 留言系统

基于 GitHub Discussions 的博客评论系统，无需数据库，简洁高效。

一、功能特性

二、工作原理

访客评论 → Giscus 前端 → GitHub API → 创建/更新 Discussion
                                        ↓
    访客查看 ← Giscus 前端 ← GitHub API ← Discussion 数据
    

1. 访客在博客评论 → Giscus 调用 GitHub API
2. 系统在仓库中创建对应的 Discussion（每个页面一个 Discussion）
3. 评论数据存储在 GitHub Discussions 中
4. 其他访客查看评论时，从 Discussions 读取并展示

三、启用条件

3.1 仓库要求

3.2 安装 Giscus App

1. 打开 https://github.com/apps/giscus
2. 点击 "Install"
3. 选择 "Only select repositories"
4. 选择你的博客仓库（如 mornikar/mornikar.github.io）
5. 点击 "Install"

3.3 开启 Discussions

1. 进入仓库 Settings
2. 找到 Features 部分
3. 勾选 "Discussions"
4. 点击 "Start discussions" 确认

四、获取配置参数

4.1 访问 Giscus 配置页

打开 https://giscus.app/zh-CN

4.2 配置参数

4.3 创建 Discussion 分类

1. 在 Giscus 页面的「分类」下拉框中
2. 点击 "Create a new category"
3. 名称输入：Announcements
4. 类型选择：**"Announcements"**（公告类型）
5. 点击 "Create"

💡 推荐使用公告类型分类：这样只有仓库维护者和 Giscus 机器人能创建新 Discussion，访客只能在现有 Discussion 下评论，避免垃圾评论。

4.4 复制配置

配置完成后，页面会显示生成的代码，例如：

<script src="https://giscus.app/client.js"
            data-repo="mornikar/mornikar.github.io"
            data-repo-id="R_kgDOPto6vw"
            data-category="Announcements"
            data-category-id="DIC_kwDOPto6v84C7YeI"
            data-mapping="pathname"
            data-strict="0"
            data-reactions-enabled="1"
            data-emit-metadata="1"
            data-input-position="top"
            data-theme="preferred_color_scheme"
            data-lang="zh-CN"
            data-loading="lazy"
            crossorigin="anonymous"
            async>
    </script>
    

记录以下三个关键参数：

• data-repo-id
• data-category-id

五、配置博客

5.1 修改主题配置

编辑 themes/arknights/_config.yml，找到 giscus 配置：

# Giscus
    giscus:
      enable: true
      repo: 你的用户名/仓库名
      repo_id: 从 giscus.app 获取的仓库 ID
      category: Announcements
      category_id: 从 giscus.app 获取的分类 ID
      mapping: pathname
      input_position: top
      theme: preferred_color_scheme
      lang: zh-CN
      loading: lazy
    

5.2 配置参数说明

5.3 主题配置示例

方案一：跟随网站明暗（推荐）

theme: preferred_color_scheme
    

方案二：固定亮色

theme: light
    

方案三：固定暗色

theme: dark
    

方案四：明暗分开配置

theme_light: light
    theme_dark: dark_dimmed
    

六、推送更新

# 提交更改
    git add themes/arknights/_config.yml
    git commit -m "feat: 启用 Giscus 留言功能"
    git push origin source
    
    # CI 自动构建部署，2 分钟后生效
    

七、验证效果

1. 打开博客任意文章
2. 滚动到文章底部
3. 应能看到 Giscus 评论区
4. 点击评论框，使用 GitHub 账号登录
5. 尝试发表一条测试评论

八、常见问题

Q1: 评论没有出现？

1. 确认 giscus.enable: true
2. 检查浏览器 Console 是否有报错
3. 确认 Giscus App 已安装到仓库
4. 确认 Discussions 已开启

Q2: 如何自定义评论样式？

Giscus 支持自定义 CSS，通过 theme 参数可以加载自定义样式文件：

theme: https://your-domain.com/custom-giscus.css
    

Q3: 可以关闭某篇文章的评论吗？

在文章 frontmatter 中添加：

comments: false
    

Q4: 评论数据存在哪里？

评论存储在 GitHub Discussions 中，可以直接访问仓库的 Discussions 页面查看和管理。

九、进阶配置

9.1 启用评论反应

reactions_enabled: 1
    

9.2 输出元数据

emit_metadata: 1
    

9.3 严格标题匹配

strict: 1
    

9.4 限制访问域名

origin: https://your-domain.com
    

十、相关链接