Giscus 配置速览：5 步启用评论系统

这篇文章只关注 Giscus 接入流程，不重复组件总览中的其他内容。

第 1 步：准备仓库

• 确保仓库是公开仓库。
• 在 GitHub 仓库设置中启用 Discussions。
• 建议先创建一个用于评论的分类，例如 Announcements 或 General。

第 2 步：安装 Giscus App

• 访问 https://github.com/apps/giscus 并安装到目标仓库。
• 在 https://giscus.app/zh-CN 选择仓库和 Discussion 分类。

完成后你会拿到以下关键值：

• repo：owner/repo
• repoId：仓库 ID
• category
• categoryId

第 3 步：写入 consts.ts

在 src/consts.ts 的 COMMENTS 中填入配置：

export const COMMENTS = {
	enabled: true,
	provider: 'giscus',
	repo: 'kevynf/kevynf.github.io',
	repoId: '你的 repoId',
	category: 'Announcements',
	categoryId: '你的 categoryId',
	mapping: 'pathname',
	themeLight: '/giscus/light.css',
	themeDark: '/giscus/dark.css',
	lang: 'zh-CN',
};

第 4 步：按文章控制评论开关

在文章 frontmatter 中添加 enableComments 字段即可按文章独立控制：

---
title: 我的文章
enableComments: false
---

模板会优先读取 frontmatter 中的值，未设置时默认开启评论。

如果设为 false，即使 COMMENTS.enabled 为 true 该文章也不会渲染评论区。

第 5 步：常见问题排查

• 页面显示“评论系统尚未配置，请检查 src/consts.ts 中的 COMMENTS 设置。”
  • 检查 repo、repoId、categoryId 是否为空。
• 评论区加载失败或无内容
  • 检查仓库是否公开、Discussions 是否开启、分类是否匹配。
• 主题切换后评论区颜色不正确
  • 检查 themeLight / themeDark 是否为 Giscus 支持的主题名。

可选参数建议

• mapping
  • 推荐 pathname，按 URL 路径绑定讨论串。
  • 若希望按文章标题绑定，可使用 title。
• lang
  • 可设置 zh-CN、en 等。
• themeLight / themeDark
  • 默认使用 public/giscus/light.css 与 dark.css，配色、字体和圆角与站点 token 保持一致；修改 global.css 的颜色后需同步更新这两个文件。
  • 也可改回 giscus 官方主题名，例如 light、dark、transparent_dark。
  • 自定义主题由 giscus iframe 跨域加载，部署环境需返回 CORS 头（GitHub Pages 默认满足）。
• 默认排序
  • giscus 默认按「最早」排序，且无法按页面单独设置。
  • 仓库根目录的 giscus.json 可全局修改，本站设为 {"defaultCommentOrder": "newest"}，所有评论区默认最新在前，访客仍可手动切换。
  • 该文件由 giscus 从 GitHub 仓库的默认分支读取，推送后才生效。