Giscus 从零配置到上线：GitHub Discussions 评论系统完整指南 | 程序员飞云

先说结论：如果你是第一次接入，按这个默认方案走

对于当前项目，推荐你先用下面这组默认值，不要一上来就做高级定制：

comment: {
  provider: "giscus",
  giscus: {
    repo: "owner/repo",
    repoId: "...",
    category: "General",
    categoryId: "...",
    mapping: "pathname",
    term: "",
    strict: "1",
    reactionsEnabled: "1",
    emitMetadata: "0",
    inputPosition: "top",
    lang: "zh-CN",
    loading: "lazy",
    themeLight: "light",
    themeDark: "dark"
  }
}

原因：

pathname 最稳定，适合博客、教程和 Vercel 部署。
strict: "1" 能避免错绑到其他 discussion。
loading: "lazy" 对静态站更友好。
emitMetadata: "0" 适合大多数站点，本项目默认不监听 giscus 元数据事件。
themeLight/themeDark 明确写死，比依赖自动推断更可控。

如果你照着本文一步一步做，第一次接入优先使用这一组参数。

官方文档与本文的关系

这篇教程以 giscus 官方文档为基础，再补上当前项目里的具体落点。

官方配置页：https://giscus.app/zh-CN
高级用法：https://github.com/giscus/giscus/blob/main/ADVANCED-USAGE.md

官方文档告诉你“giscus 能做什么”；本文告诉你“在这个项目里该怎么做，为什么这么做，出问题先查哪里”。

giscus 是什么，它到底怎么工作

giscus 是一个基于 GitHub Discussions 的评论系统。

它的核心逻辑是：

页面加载评论区时，giscus 会根据你配置的映射方式去 GitHub Discussions 里找匹配的 discussion。
如果找到了，就把那个 discussion 当作这篇文章的评论区。
如果没找到，那么第一次有人发表评论时，giscus bot 会自动创建 discussion。
评论者需要通过 GitHub OAuth 授权，或者直接去 GitHub Discussions 页面评论。

这意味着：

你不需要数据库。
你的评论数据在 GitHub 仓库的 Discussions 里。
你需要先把 GitHub 仓库侧的前置条件准备好。

第一步：准备 GitHub 仓库

这是新手最容易漏的环节。
评论不显示，很多时候不是页面问题，而是仓库准备没完成。

1. 仓库必须公开

giscus 官方要求目标仓库是公开仓库。
如果仓库是私有的，评论系统通常不能正常工作。

2. 启用 GitHub Discussions

进入 GitHub 仓库：

打开 Settings
找到 Features
勾选 Discussions

如果 Discussions 根本没有开启，giscus 没法为你创建评论对应的 discussion。

3. 安装 giscus app

进入 giscus 官方配置页时，会提示你安装 giscus app。
你需要把它安装到目标仓库，至少保证当前仓库有权限。

如果没装 app，常见现象是：

页面能显示占位，但无法正常创建 discussion
评论登录后仍无法发表评论

4. 创建用于评论的分类

在 GitHub Discussions 里创建一个分类，例如：

General
Comments
Announcements

对于新手，推荐你先用一个专门的评论分类，不要混进技术讨论、公告、提问等其他讨论。

5. 关于 `Announcements` 的说明

giscus 官方配置页会推荐使用 Announcements 类型分类，因为这种分类通常只有维护者和 giscus bot 可以创建新 discussion，更适合把 discussion 的创建入口收敛到评论系统本身。
但这不是硬性要求。

对于当前项目：

如果你已经有 General，直接先用 General 也完全可以。
如果你准备长期维护，建议后面迁到专用评论分类。

第二步：去 giscus 官方配置页生成参数

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

你会在页面上看到一整套表单。
不要急着复制最终脚本，先理解每个字段是什么意思。

第三步：理解每个配置字段

`repo`

格式：owner/repo

示例：

flycodeu/FlyCodeCenter

作用：

告诉 giscus 评论数据要落在哪个 GitHub 仓库。

常见错误：

仓库名写错
写成私有仓库
写成 fork 仓库但 Discussions 实际开在别的仓库

`repoId`

这是 GitHub 给仓库分配的内部 ID。
通常直接从 giscus 官方配置页复制，不要手填。

`category`

discussion 分类名，例如 General、Comments、Announcements。

`categoryId`

和 repoId 一样，直接从官方页面复制，不要手动猜。

`mapping`

这是最关键的字段之一，它决定“当前页面如何对应到某个 discussion”。

当前项目里常见可选值：

值	含义	是否推荐给新手
`pathname`	用路径映射，例如 `/article/sg0106/`	推荐
`url`	用完整 URL 映射	不推荐
`title`	用页面标题映射	不推荐
`og:title`	用 Open Graph 标题映射	一般不推荐
`specific`	手动指定固定讨论项	仅高级场景
`number`	手动指定固定 discussion 编号	仅高级场景

为什么默认推荐 `pathname`

因为当前项目是内容站，文章地址是天然稳定标识。

用 pathname 的好处：

本地、预览、正式环境只要路径一致，就能命中同一个 discussion
不受域名变化影响
适合博客、教程、文档页

为什么不推荐 `url`

如果你部署在 Vercel，Preview 和 Production 的域名不同。
一旦用 url，同一篇文章可能会被当成两篇不同页面，造成 discussion 分裂。

`specific` / `number` 什么时候用

只有在这些场景下才建议用：

迁移老站时，想把新旧页面强行绑到同一个 discussion
多个页面共用一个讨论串
你明确知道要绑哪个 discussion

它们都要求你提供 term。

`term`

只在 mapping = "specific" 或 mapping = "number" 时使用。

specific：通常填一个你自己定义的稳定字符串
number：填 discussion 编号

如果你只是普通博客/教程站用户，不要先碰它。

`strict`

推荐值："1"

作用：

控制 discussion 搜索是否严格匹配。

为什么推荐开启：

能减少因为标题、路径相近导致的错绑
更适合一篇文章只对应一个 discussion 的内容站

`reactionsEnabled`

推荐值："1"

作用：

是否允许点赞等 reaction。

建议：

默认开着，用户体验更完整。
如果你不希望评论区偏社交化，可以再关掉。

`emitMetadata`

推荐值："0"

作用：

允许 giscus 向父页面发送更多元数据事件。

为什么本项目默认关掉：

当前项目没有消费这类事件
新手接入阶段没必要增加变量

只有当你后面要自己监听 postMessage 事件时，再打开它。

`inputPosition`

推荐值："top"

作用：

决定评论输入框在评论列表的上面还是下面。

为什么推荐 top：

技术博客更适合先看到输入框
首次访客更容易理解“这里可以评论”

`lang`

推荐值："zh-CN"

作用：

giscus UI 语言。

如果你的站点主要是中文内容，直接用 zh-CN。

`loading`

推荐值："lazy"

作用：

决定 iframe 是懒加载还是尽早加载。

为什么默认推荐 lazy：

文章首屏先保证正文可读
评论区通常在文章底部，没必要抢首屏资源
对静态站性能更友好

`themeLight` / `themeDark`

推荐值：

themeLight = light
themeDark = dark

作用：

明确站点浅色/深色主题分别映射成什么 giscus 主题。

当前项目已经做了主题同步逻辑，所以你需要关注的是“映射成什么”，而不是“能不能同步”。

第四步：把参数填进当前项目

当前项目的配置入口在 site.config.ts。

方案 A：直接写进 `site.config.ts`

适合本地开发、个人站点、单环境维护。

comment: {
  provider: "giscus",
  giscus: {
    repo: "owner/repo",
    repoId: "R_kgDO...",
    category: "General",
    categoryId: "DIC_kwDO...",
    mapping: "pathname",
    term: "",
    strict: "1",
    reactionsEnabled: "1",
    emitMetadata: "0",
    inputPosition: "top",
    lang: "zh-CN",
    loading: "lazy",
    themeLight: "light",
    themeDark: "dark"
  }
}

方案 B：通过环境变量注入

适合 GitHub + Vercel 场景，后面部署更方便。

PUBLIC_GISCUS_REPO=owner/repo
PUBLIC_GISCUS_REPO_ID=R_kgDO...
PUBLIC_GISCUS_CATEGORY=General
PUBLIC_GISCUS_CATEGORY_ID=DIC_kwDO...
PUBLIC_GISCUS_MAPPING=pathname
PUBLIC_GISCUS_TERM=
PUBLIC_GISCUS_STRICT=1
PUBLIC_GISCUS_REACTIONS_ENABLED=1
PUBLIC_GISCUS_EMIT_METADATA=0
PUBLIC_GISCUS_INPUT_POSITION=top
PUBLIC_GISCUS_LANG=zh-CN
PUBLIC_GISCUS_LOADING=lazy
PUBLIC_GISCUS_THEME_LIGHT=light
PUBLIC_GISCUS_THEME_DARK=dark

本项目在构建时会把这些 PUBLIC_GISCUS_* 变量读进 site.config.ts。

第五步：理解当前项目里的主题同步

当前项目不是把 giscus 主题固定写死，而是会在运行时跟随站点主题切换。

实现位置：

同步逻辑是：

站点切换主题时，会触发 site:theme-change
Giscus.astro 监听这个事件
然后把新的 theme 发给 giscus iframe

这也是为什么我们推荐把浅色和深色主题分开配置，而不是只在官方页面随便选一个默认主题。

第六步：第一次真正验证评论是否可用

配置完成后，不要只看“评论框有没有出现”，而要做完整验证。

最低验证步骤

本地启动站点
打开任意一篇文章
滚动到评论区
确认 giscus iframe 已加载
点击登录 GitHub
发一条测试评论
回 GitHub 仓库 Discussions，确认是否自动创建 discussion
刷新文章页，确认原评论仍能命中
切换浅色/深色主题，确认评论 iframe 跟着变化

首次评论时会发生什么

如果当前页面还没有对应 discussion：

你第一次发表评论时
giscus bot 会帮你自动创建 discussion
以后再访问这篇文章，就会直接命中它

这一步是正常行为，不是“评论区突然帮你新建了奇怪讨论”。

第七步：高级用法先知道，不要一开始就上

giscus 除了页面配置，还支持仓库级的 giscus.json。

高级用法文档：https://github.com/giscus/giscus/blob/main/ADVANCED-USAGE.md

1. `origins`

适合你只允许某几个正式域名嵌入评论时使用。

示意：

{
  "origins": [
    "https://www.example.com",
    "https://docs.example.com"
  ]
}

2. `originsRegex`

适合预览域名很多、规则型匹配的情况，比如 Vercel 预览域名。

示意：

{
  "originsRegex": [
    "https://.*\\.vercel\\.app"
  ]
}

3. `defaultCommentOrder`

适合你想控制评论默认按最旧还是最新排序。

示意：

{
  "defaultCommentOrder": "newest"
}

4. `giscus:backlink`

高级用法支持通过 discussion frontmatter 配置回链，让 GitHub Discussions 能更精确地回到你的网站页面。
这是仓库讨论侧能力，不是当前项目前端脚本字段。

5. 当前项目对高级用法的态度

当前项目这轮接入重点是：

把基础评论能力稳定跑通
把常用字段补齐
把教程写清楚

origins / originsRegex / defaultCommentOrder / giscus:backlink 这些能力建议在你确认基础接入稳定后，再按高级用法文档启用。

最常见的错误和排查方法

1. 页面完全没有评论框

优先检查：

provider 是否真的是 giscus
repo / repoId / category / categoryId 是否完整
如果 mapping 是 specific 或 number，term 是否填写

2. 看到评论区提示，但没有 iframe

这通常说明当前项目已经检测到配置缺项。
看页面提示里缺的是哪一个字段，然后回 site.config.ts 或环境变量补齐。

3. 登录了 GitHub 但还是不能评论

优先检查：

giscus app 是否安装到目标仓库
仓库是否公开
GitHub Discussions 是否启用
你是否真的给当前仓库安装了权限，而不是装到了别的仓库

4. 首次评论后没有自动创建 discussion

优先检查：

分类是否有效
category / categoryId 是否匹配
仓库 Discussions 是否开启
giscus app 是否安装成功

5. 同一篇文章反复新建 discussion

优先检查：

mapping 是否选错
标题是否频繁变化且使用了 title
是否用了 url 导致不同域名环境被视为不同页面

对于当前项目，这也是为什么默认推荐 pathname。

6. 不同文章命中到同一个 discussion

优先检查：

是否错误使用了 specific
term 是否写成固定值却在多个页面共用
是否标题重复但使用了 title

7. 主题不跟随站点切换

优先检查：

themeLight / themeDark 是否填写正确
当前页面是否真的触发了站点主题切换
Giscus.astro 是否仍在使用项目内默认逻辑，而不是被你本地改坏

8. 本地正常、线上不正常

优先检查：

Vercel 环境变量是否配置到正确环境
配完环境变量后是否重新部署
是否使用 url 映射导致 Preview/Production 分裂
如果启用了 giscus.json 的 origins，线上域名是否被允许

当前项目里，哪些字段最值得你长期记住

如果只记住 5 个点，记这 5 个：

provider = "giscus"
mapping = "pathname"
strict = "1"
loading = "lazy"
themeLight/themeDark 要跟站点主题策略一起看

本篇结论

对第一次接入的用户来说，最重要的不是“把脚本贴上去”，而是：

先把 GitHub 仓库准备对
再从官方页面拿准确参数
再用本项目推荐配置落到 site.config.ts
最后做一次真正的评论和主题验证

只要这四步不跳，giscus 在这个项目里通常能一次接通。

下一步怎么走

想了解评论系统的第二条 GitHub 路线：看 07-utterances-and-fallback-strategy.md
想把当前配置带到线上：看 20-github-vercel-deploy-full-workflow.md
已经上线但评论还是不正常：看 21-env-vars-troubleshooting-and-release-checklist.md

先说结论：如果你是第一次接入，按这个默认方案走

官方文档与本文的关系

giscus 是什么，它到底怎么工作

第一步：准备 GitHub 仓库

1. 仓库必须公开

2. 启用 GitHub Discussions

3. 安装 giscus app

4. 创建用于评论的分类

5. 关于 Announcements 的说明

第二步：去 giscus 官方配置页生成参数

第三步：理解每个配置字段

repo

repoId

category

categoryId

mapping

为什么默认推荐 pathname

为什么不推荐 url

specific / number 什么时候用

term

strict

reactionsEnabled

emitMetadata

inputPosition

lang

loading

themeLight / themeDark

第四步：把参数填进当前项目

方案 A：直接写进 site.config.ts

方案 B：通过环境变量注入

第五步：理解当前项目里的主题同步

第六步：第一次真正验证评论是否可用

最低验证步骤

首次评论时会发生什么

第七步：高级用法先知道，不要一开始就上

1. origins

2. originsRegex

3. defaultCommentOrder

4. giscus:backlink

5. 当前项目对高级用法的态度

最常见的错误和排查方法

1. 页面完全没有评论框

2. 看到评论区提示，但没有 iframe

3. 登录了 GitHub 但还是不能评论

4. 首次评论后没有自动创建 discussion

5. 同一篇文章反复新建 discussion

6. 不同文章命中到同一个 discussion

7. 主题不跟随站点切换

8. 本地正常、线上不正常

当前项目里，哪些字段最值得你长期记住

本篇结论

下一步怎么走

评论

5. 关于 `Announcements` 的说明

`repo`

`repoId`

`category`

`categoryId`

`mapping`

为什么默认推荐 `pathname`

为什么不推荐 `url`

`specific` / `number` 什么时候用

`term`

`strict`

`reactionsEnabled`

`emitMetadata`

`inputPosition`

`lang`

`loading`

`themeLight` / `themeDark`

方案 A：直接写进 `site.config.ts`

1. `origins`

2. `originsRegex`

3. `defaultCommentOrder`

4. `giscus:backlink`