配置字典:Giscus 评论和多语言讨论共享
文章与碎片的独立开关、讨论映射、语言和共享规则。
文章目录
初次配置先读让读者留下评论,其中包含仓库准备和参数获取。配置文件位置见安装与站点信息,其他模块从配置字典总入口进入。
公共配置写在 src/site.config.ts 的 theme.comments 中;评论默认关闭。下面列主题包默认值,不以 demo 已连接的个人仓库为准。ID 和仓库参数会写入页面,是公开连接信息,不要把 GitHub 访问令牌或其他秘密填进去。
先分清两个评论开关
| 路径 | 类型 / 默认值 | 状态、作用与限制 | 示例 |
|---|---|---|---|
| theme.comments.enabled | boolean / false | 条件生效:文章评论;不控制碎片按钮。文章连接参数缺失时可能不输出评论区,不代表远端服务已验证成功 | theme: { comments: { enabled: true } } |
| theme.fragments.comments.enabled | boolean / false | 条件生效:碎片列表评论;还需 theme.fragments.enabled 为 true。独立于文章开关,必填连接字段缺失会在生成碎片页时报错 | theme: { fragments: { enabled: true, comments: { enabled: true } } } |
文章没有单篇 comments: false frontmatter 开关。碎片也没有每条单独的评论开关;首页碎片预览不显示评论按钮。碎片其他设置见Fragments 字典。
theme.comments 的全部字段
下表字段的完整前缀均为 theme.comments.,例如 repo 的完整路径是 theme.comments.repo。所有字段在输入的部分配置中均可省略,由主题默认值补齐。字符串标志必须保留引号,不能写成 true/false 或数字。
这些字段都是条件生效:文章评论需要启用并满足输出条件;碎片仅使用其中一部分,其余会覆盖或忽略。没有通用的“空字符串恢复默认”规则,具体见每行。除明确校验的映射约束外,类型正确和非空不等于 Giscus 远端配置正确。
仓库与分类
| 字段 | 类型 | 默认值 | 作用、条件与限制 | 示例值 |
|---|---|---|---|---|
repo |
string | "" |
GitHub 的 owner/repo。文章侧要求值为真才输出;碎片侧还检查 trim 后非空。不要加首尾空格;主题不检查远端权限 | "your-account/blog-discussions" |
repoId |
string | "" |
Giscus 配置工具提供的仓库 ID,不是仓库名、数字序号或访问令牌;文章与碎片共用 | "YOUR_REPOSITORY_ID" |
category |
string | "" |
讨论分类名称;填写 Giscus 提供的分类并与 categoryId 配套;不是博客文章标签 | "Announcements" |
categoryId |
string | "" |
Giscus 提供的分类 ID,不是分类名称。文章要求值为真;碎片要求 trim 后非空,不验证远端真实性 | "YOUR_CATEGORY_ID" |
文章映射与严格匹配
| 字段 | 类型 | 默认值 | 作用、条件与限制 | 示例值 |
|---|---|---|---|---|
mapping |
‘pathname’ | ‘url’ | ‘title’ | ‘og:title’ | ‘specific’ | ‘number’ | "pathname" |
文章与讨论的关联方式,逐值含义见下文。共享模式必须 specific;碎片不使用这个字段 | "pathname" |
term |
string | "" |
非共享文章在 specific 模式使用,去除首尾空白后必须非空;这是全站固定 term。共享模式必须留空,渲染时按文章 slug 填入;其他模式不传此项 | "my-fixed-discussion" |
number |
string | "" |
非共享文章在 number 模式使用,trim 后必须为安全范围内的正整数字符串,不允许前导零、正号或小数;共享模式必须留空。其他模式不传此项 | "42" |
strict |
‘0’ | ‘1’ | "0" |
文章严格匹配标志;是字符串而非 boolean。共享模式要求 1;碎片固定覆盖为 1。并非将两个相同标题的讨论自动合并 | "1" |
显示、语言和加载
| 字段 | 类型 | 默认值 | 作用、条件与限制 | 示例值 |
|---|---|---|---|---|
reactionsEnabled |
‘0’ | ‘1’ | "1" |
显示讨论主帖的反应区域;文章与碎片共用,不等于禁用所有评论操作 | "1" |
emitMetadata |
‘0’ | ‘1’ | "0" |
让 Giscus 向父窗口发送讨论元数据;文章按设置传递,不会因此自动显示评论统计。碎片固定为 1,供加载及讨论切换状态判断 | "0" |
inputPosition |
‘top’ | ‘bottom’ | "bottom" |
评论输入框在评论列表上方或下方;文章与碎片共用,不改变整个评论区在页面的位置 | "top" |
theme |
string | "dark" |
传给 Giscus 的 iframe 主题,不是博客 Matrix/Cyber/Hacker/AI 场景。文章与碎片共用;主题不校验服务支持的名称,也不会自动随页面场景切换 | "dark" |
lang |
string | "en" |
文章评论界面语言。非空值直接传给 Giscus;空字符串按页面语言映射。碎片始终跟随页面,忽略此项。不翻译评论正文 | "" |
loading |
‘lazy’ | ‘eager’ | "lazy" |
文章 iframe 加载提示;不是延迟输出整个 client.js。碎片固定 eager,但点击评论按钮后才插入客户端 | "lazy" |
crossorigin |
‘anonymous’ | ‘use-credentials’ | "anonymous" |
传给 Giscus 客户端 script 的 crossorigin 属性,文章与碎片共用;不是仓库登录凭据、GitHub token 或解决权限问题的开关 | "anonymous" |
theme.comments.shareAcrossLocales:文章译文共享
- 类型 / 默认值: boolean,可省略 / false。
- 状态与作用: 条件生效;文章评论开启后,让相同完整 slug 的不同语言版本绑定同一个讨论。不同 slug 保持分开。
- 限制: 要求 mapping 为 ‘specific’,term 和 number 在 trim 后均为空,strict 为字符串 ‘1’;不满足会报配置错误,不能只打开布尔开关。关闭文章评论时跳过这组启用约束,但碎片仍有自己的连接检查。
- 示例: 下方共享配置片段。它不会翻译评论、合并旧讨论或改变碎片绑定方式。
| 文章文件 | 共享模式实际 term |
|---|---|
| src/content/blog/zh/my-first-post.md | my-first-post |
| src/content/blog/en/my-first-post.md | my-first-post |
| src/content/blog/zh/guides/setup.md | guides/setup |
| src/content/blog/en/other/setup.md | other/setup |
按完整、不含语言目录的 slug 关联,不根据文章标题、canonicalTopic 或正文自动识别译文。共享模式下标准文章路由会传入 articleSlug;自定义调用 BlogPost 也必须提供非空、无首尾空白、无空路径段及 . / .. 段的完整 slug。这个组件参数不是 site.config 字段。
同一个仓库与分类中,同 slug 的多个网站也可能命中相同讨论。它不是按域名额外隔离的数据库。保留路径的前提下,改变标题不改变共享 term;改 slug、仓库、分类或匹配策略可能关联到另一条讨论。
mapping 各值的含义
| 值 | Giscus 使用的依据 | 限制及例子 |
|---|---|---|
| pathname | 页面的 URL 路径 | 默认值;不同语言路径通常不同,改路径可能改变关联 |
| url | 完整页面 URL | 换域名或地址可能影响关联 |
| title | 文档 title | 更改文章或站点标题可能影响关联,不是只看正文 h1 |
| og:title | 页面 Open Graph 标题 | 取页面已有元信息,不通过 theme.comments 填标题 |
| specific | 指定 term | 非共享时是全站固定词;共享时由每篇文章 slug 生成 |
| number | 已有 Discussion 编号 | 全站指向固定编号,填字符串如 ‘42’;不是 issue 编号,也不会自动创建讨论 |
以上关联与创建行为交给 Giscus:未找到讨论时,可在首次评论或反应时创建,单纯打开页面不保证创建。仓库需公开、启用 Discussions 并安装 Giscus 应用;具体操作见教程与Giscus 官方配置页。主题不在本地保存评论数据库。
strict 为 ‘1’ 时,Giscus 使用讨论正文中的标题哈希做严格匹配,不是主题在本地比较两个标题。早期已有讨论可能需要补充匹配标记;参见Giscus 严格匹配说明。启用共享或更改映射不会自动迁移、合并、删除旧讨论;旧评论可能仍在 GitHub,但不出现在新绑定下。迁移前先确定现有讨论与新 term 的对应关系。
非共享时,specific + 一个固定 term 会让所有使用该配置的文章寻找同一讨论;number 也会全站指向同一编号。它们不是“每篇文章自动分配一个 ID”。与当前映射无关的 term/number 不发送给 Giscus;主题仍会对这两个配置值执行 trim,因此不要用 null 或数字替代字符串。
可合并的配置示例
合并进 src/site.config.ts 现有 defineThemeConfig({…}),保留 import、export 和其他个人配置,不重复创建 theme。四个连接值必须从你自己的 Giscus 配置获取;下方占位值只能说明结构,不能用于线上验证。
文章评论按路径分开
theme: {
comments: {
enabled: true,
repo: 'your-account/blog-discussions',
repoId: 'YOUR_REPOSITORY_ID',
category: 'Announcements',
categoryId: 'YOUR_CATEGORY_ID',
shareAcrossLocales: false,
mapping: 'pathname',
lang: '',
},
},
同一篇文章的译文共用讨论
保留自己的连接参数,并将映射部分合并为:
theme: {
comments: {
enabled: true,
shareAcrossLocales: true,
mapping: 'specific',
term: '',
number: '',
strict: '1',
lang: '',
},
},
默认 lang 实际为 ‘en’,不是“跟随页面”;上面明确用空字符串启用页面语言映射。zh 转为 zh-CN、zh-hant 转为 zh-TW、pt-br 转为 pt,其他代码直接传入。语言是否被 Giscus 支持由服务决定;更改语言只改界面,不改变讨论身份或翻译已发评论。theme.comments 是全站配置,不在 i18n.locales 内分别复制。
theme 字符串直接传给 Giscus,常用例值是 ‘dark’ 或 ‘light’;可用主题以及自定义 CSS 网址由 Giscus 负责,不会改变外层 AI 面板。需要自定义时查官方主题说明,主题包不会验证自定义 CSS 的内容和可访问性。
碎片评论使用公共配置的哪些部分?
| 公共字段 | 碎片实际行为 |
|---|---|
| repo / repoId / category / categoryId | 共用;四项 trim 后必须非空。原值继续传递,配置时不要加首尾空白;不验证远端权限 |
| theme / reactionsEnabled / inputPosition / crossorigin | 共用原设置 |
| enabled | 忽略文章开关,使用 theme.fragments.comments.enabled |
| shareAcrossLocales | 不使用;同一稳定 ID 本身就绑定同一讨论 |
| mapping / term / number | 固定 specific,term 为 fragment/<ID>,不发送 number |
| strict / emitMetadata | 固定 ‘1’ / ‘1’ |
| lang | 不使用公共 lang,始终按当前碎片页面语言映射 |
| loading | 固定 eager,但首次点击评论按钮后才插入客户端 |
例如只开启碎片评论、关闭文章评论:
theme: {
comments: {
enabled: false,
repo: 'your-account/blog-discussions',
repoId: 'YOUR_REPOSITORY_ID',
category: 'Announcements',
categoryId: 'YOUR_CATEGORY_ID',
},
fragments: { enabled: true, comments: { enabled: true } },
},
同 ID 的多语言碎片共享 fragment/<ID>,与文章 slug 共享是两套规则。不要为改变排序或分页修改稳定 ID。弹窗首次点击才加载;关闭后保留 iframe,切换内容通过 Giscus 配置消息更新讨论,约 15 秒没有有效加载结果会显示失败与重试。没有公开的评论超时或预加载配置。即使只想配置碎片,如果同时启用文章评论,文章映射校验仍会执行。
页面自身的评论文案
这些是 i18n.locales.<语言>.messages 下的 string 字段,均可省略,默认使用当前语言内置文案与回退链。示例值写到对应对象;只改变外层标签,不替换 Giscus iframe 内部按钮。表中仅列中文 / 英文默认值。
| 相对字段 | 中文 / 英文默认值 | 状态、作用与限制 | 示例值 |
|---|---|---|---|
blog.comments |
评论 / Comments | 条件生效:文章评论区域的无障碍名称,不是可见的额外标题 | "文章讨论" |
fragments.comments |
评论 / Comments | 条件生效:碎片评论按钮与弹窗标题 | "参与讨论" |
fragments.close |
关闭 / Close | 条件生效:弹窗关闭按钮;也用于首页碎片窗口关闭的无障碍名称 | "关闭窗口" |
fragments.loading |
正在加载评论… / Loading comments… | 条件生效:碎片评论加载状态 | "正在加载讨论…" |
fragments.error |
评论未能加载,请检查网络或评论配置后重试。 / Unable to load comments. Check your network or comment settings, then retry. | 条件生效:碎片评论失败提示 | "讨论暂时不可用。" |
fragments.retry |
重试 / Retry | 条件生效:碎片评论失败后的重试按钮 | "重新加载" |
文章和碎片其他文案分别见文章字典和Fragments 字典。这些字段不决定 iframe 内部语言,后者使用前文的 lang 规则。
加载与校验边界
文章输出异步 client.js;loading: ‘lazy’ 传给 Giscus iframe,并不表示主题等滚动到评论区才插入 script。碎片则先输出模板,点击后才插入客户端;它的 eager 指点击后的 iframe 行为。官方加载说明区分了这两层。
本地代码检查文章映射约束和碎片必填项,不证明 GitHub 登录、应用授权、仓库可见性、分类、网络或服务端可用。文章连接字段为空时可能直接不渲染;只含空格的字符串仍可能通过文章输出条件,不能当成正确配置。碎片的非空检查更严格,但同样不能验证 ID 真伪。
目前所有 theme.comments 字段都有消费位置;不是所有字段都对碎片生效,覆盖关系已列出。不存在公开的单篇评论开关、自托管服务地址、评论排序、管理员 token 或本地数据库配置;客户端固定使用 https://giscus.app/client.js。Giscus 自身的仓库级配置不等于新增的 site.config 字段。
修改配置后重新构建部署;构建通过不等于真实评论服务验收通过。已有讨论的迁移和权限操作需在 GitHub/Giscus 侧处理,不会在保存 site.config 时自动完成。返回配置总入口查其他模块。