后端【免费下载链接】giscusA commenting system powered by GitHub Discussions. :octocat: :speech_balloon: :gem:项目地址https://gitcode.com/gh_mirrors/gi/giscus点击查看免费下载giscus 是一个完全依托 GitHub Discussions 构建的开源评论系统让网站访客通过 GitHub 账号即可发表评论与表情回应。本文以仓库中的 README.pl.md项目主 README 的波兰语译本内容与 README.md 一致为主体结合仓库源码深入解析其工作原理、核心特性、配置方式与迁移方案。读完本文你将理解 giscus 如何用 GitHub Discussions 替代自建数据库与后端评论服务并掌握giscus.json、data-属性等进阶配置的实战用法。项目概览giscus 是什么giscus 是一个由 GitHub Discussions 驱动的评论系统A comments system powered by GitHub Discussions。访客可以在你的网站上通过 GitHub 发表评论和表情回应而所有的评论数据都存放在 GitHub 的 Discussion 中无需自建任何数据库。该项目深受 utterances 启发但与 utterances 基于 GitHub Issues 不同giscus 基于 GitHub Discussions。从 README 中可以直接概括出它的核心卖点开源项目以开放源代码的形式发布任何开发者都可以查看、部署和二次开发。无追踪、无广告、永久免费不采集访客数据不插入广告。无需数据库所有数据全部存储在 GitHub Discussions 中评论即Issue/讨论数据。支持自定义主题不仅内置多套主题还允许通过 CSS 文件自定义外观。支持多语言内置数十种语言的界面翻译。高度可配置通过仓库根目录的giscus.json和script标签的data-属性进行深度定制。自动同步自动从 GitHub 拉取新的评论与编辑内容。可自托管可以部署在自己的服务器上详见仓库中的 SELF-HOSTING.md。README 中特别强调了一个重要前提giscus 仍处于积极开发阶段GitHub 也在持续演进 Discussions 及其 API因此部分功能可能随时间变化或出现不兼容。这意味着使用时建议关注项目更新与 GitHub API 变更。工作原理从页面映射到 Discussion 的完整链路README 的 How it works 章节给出了最核心的机制描述其完整链路可以拆解为以下几步1. 搜索并映射 Discussion当 giscus 在页面中加载时它会调用GitHub Discussions 搜索 API根据你所选择的映射方式Mapping来查找与当前页面关联的 Discussion。可选的映射包括页面的完整 URLURL页面的pathname路径名页面的title标题等这一逻辑在仓库中由 pages/api/discussions/index.ts 的get分支实现服务端把repo、term、category、strict、number等查询参数组装成 GraphQL 查询调用 GitHub 的 search API如果命中讨论discussionCount 0则取第一个节点作为当前页面对应的讨论pages/api/discussions/index.ts否则返回 404 Discussion not found。2. 自动创建 Discussion如果找不到匹配的 Discussiongiscus bot 会在访客第一次发表评论或表情回应时自动创建一条 Discussion。前端组件 components/Widget.tsx 中的handleDiscussionCreateRequest会构造讨论正文body: # ${term}\n\n${description || }\n\n${cleanAnchor(backLink || origin)}即标题 页面描述 页面链接三段式正文随后通过POST /api/discussions调用 GitHub 的createDiscussion变更接口完成创建。值得一提的是该接口在创建时会自动在正文末尾追加 SHA-1 哈希注释见下文严格匹配部分pages/api/discussions/index.ts 中对应实现为const hashTag !-- sha1: ${await digestMessage(params.input.title)} --; params.input.body ${params.input.body}\n\n${hashTag};3. 访客授权OAuth 流程要发表评论访客必须授权 giscus app 代表自己发帖授权走的是标准的 GitHub OAuth 流程。仓库中对应模块为pages/api/oauth/authorize.ts 与 pages/api/oauth/authorized.ts发起与完成授权pages/api/oauth/token.ts换取访问令牌lib/oauth/state.ts 与 lib/oauth/encryption.ts负责会话状态session的加解密防止状态被篡改。4. 评论与审核除了通过 OAuth 在网站上评论访客也可以直接到 GitHub Discussion 页面上发表评论。站长可以直接在 GitHub 上对评论进行审核moderate、编辑或删除——因为评论数据本质上就是 GitHub 上的讨论内容GitHub 原生提供了一整套内容审核工具。从实现上看lib/adapter.ts 中的adaptDiscussion/adaptComment/adaptReply会把 GitHub GraphQL 返回的原始数据结构评论、回复、表情分组、分页信息等适配为前端组件所需的内部类型并在渲染前通过processCommentBody对评论 HTML 做安全化处理如给链接加上relnoopener noreferrer nofollow、注入代码块复制按钮等见 lib/adapter.ts。数据与同步为什么无需数据库giscus 无需数据库原因在于所有评论数据都存储在 GitHub Discussions 中GitHub 的 GraphQL API 就是它的数据库。前端通过 services/giscus/discussions.ts 中的useDiscussion基于 SWR 的无限分页 Hook按页拉取/api/discussions数据并利用 SWR 的重验证机制自动获取来自 GitHub 的新评论与编辑——这正是 README 中Automatically fetches new comments and edits from GitHub承诺的实现基础services/giscus/discussions.ts 中配置了revalidateOnFocus、revalidateOnReconnect等策略且对 403/404/429 状态跳过重试。仓库还提供了 pages/api/webhook.ts 作为 GitHub Webhook 入口用于讨论变更的事件驱动同步。多语言支持README 宣称 giscus 支持多种语言Supports multiple languages。仓库中的实现证据非常直观locales/ 目录下为每种语言提供了common.json与config.json两个翻译文件目前覆盖阿拉伯语、白俄罗斯语、保加利亚语、中文简/繁/港等数十种语言lib/i18n.tsx 中的availableLanguages常量定义了全部受支持语言的代码与名称i18n.fallbacks.json 提供语言回退映射当某语言缺少某个翻译键时回退到其基础语言。界面文案通过 next-translate 的useGiscusTranslation/Trans组件读取lib/i18n.tsx日期与相对时间则使用Intl.DateTimeFormat/Intl.RelativeTimeFormat按语言本地化展示lib/i18n.tsx并为阿拉伯语、波斯语、希伯来语设置了 RTL 方向。如果你希望为 giscus 增加新的语言翻译可参考仓库中的 CONTRIBUTING.md 中关于本地化贡献的说明。主题定制支持自定义主题是 README 的核心卖点之一。仓库内置主题位于 styles/themes/包括GitHub 风格系列light、dark、light_high_contrast、dark_high_contrast、dark_dimmed以及色觉障碍友好主题light_protanopia、light_tritanopia、dark_protanopia、dark_tritanopia极简风格noborder_light、noborder_dark、noborder_gray、transparent_dark第三方风格cobalt、purple_dark、gruvbox含gruvbox_dark/gruvbox_light、catppuccinlatte/frappe/macchiato/mocha、fropreferred_color_scheme跟随访问者系统配色偏好自动切换。lib/variables.ts 中的availableThemes常量完整罗列了这些主题名此外还允许通过data-theme传入/path/to/theme.css或https://...形式的自定义 CSS 地址Theme类型定义见 lib/variables.tsstyles/themes/custom_example.css 提供了自定义主题的参考模板。高度可配置仓库级配置giscus.jsonREADME 将Extensively configurable列为重要特性并在 Advanced usage 章节指出可以通过在仓库根目录创建giscus.json来添加额外配置例如限定允许加载 giscus 的来源域名。完整说明见 ADVANCED-USAGE.md这里结合仓库中的真实配置与源码给出核心字段解读。仓库自身的 giscus.json 内容如下{ origins: [ https://giscus.app, https://giscus.vercel.app, https://giscus-component.vercel.app ], originsRegex: [ https://giscus-git-([A-z0-9]|-)*giscus\\.vercel\\.app, https://giscus-component-git-([A-z0-9]|-)*giscus\\.vercel\\.app, http://selfhost:[0-9] ], defaultCommentOrder: oldest }origins限定可加载来源origins接受一个字符串数组giscus 会拿加载页面自身的window.origin与这些字符串逐一比较等价于string window.origin。若你的仓库不希望被任意站点嵌入使用就在giscus.json中列出允许的域名白名单。仓库中assertOrigin的实现位于 lib/config.ts在 pages/widget.tsx 中被用于设置 CSP 头来源合法时设置frame-ancestors self origins非法来源则直接设置frame-ancestors none并重定向从服务端层面拒绝被嵌入。originsRegex正则匹配来源与origins类似但接受正则表达式模式数组使用new RegExp(pattern).test(window.origin)判断来源适合覆盖动态子域名例如仓库配置中用于匹配 Vercel 预览分支域名的规则。origins与originsRegex可以组合使用若两者都为空或未定义giscus 将默认放行所有来源。defaultCommentOrder默认评论排序设置评论的默认排序方式取值oldest从旧到新或newest从新到旧默认值为oldest。该值在 pages/widget.tsx 中被读取为repoConfig.defaultCommentOrder || oldest前端 services/giscus/discussions.ts 中的useFrontBackDiscussion会根据orderBy决定前后两段评论的拼接顺序services/giscus/discussions.ts。类型定义CommentOrder oldest | newest见 lib/types/giscus.ts。更多data-属性与meta标签除了giscus.jsonREADME 提到的高度可配置还体现在script标签的data-属性上详见 ADVANCED-USAGE.mddata-strict1GitHub 搜索讨论时使用模糊匹配当存在标题相似的多个讨论时可能返回错误结果。开启严格匹配后giscus 不再用讨论标题作为搜索词而是计算讨论标题的 SHA-1 哈希并在讨论正文中搜索该哈希。giscus 自动创建的讨论都会在正文中写入形如!-- sha1: cad60a29d1b50cbeb42ec2ff630fc508afb1d2e3 --的 HTML 注释GitHub 页面上不可见如果你在启用该选项之前已有存量讨论需要手动编辑讨论、把标题的 SHA-1 哈希加到正文任意位置。仓库中POST /api/discussions正是这样生成哈希注释的pages/api/discussions/index.ts。data-theme除内置主题外可传入一个 CSS 文件 URLgiscus 会把它构建为link relstylesheet元素追加到head末尾。需要注意加载外部 CSS 可能存在安全风险请确保你信任该 CSS 的作者与提供方并让站内用户知晓这一风险。giscus:backlinkmeta标签如果页面带有meta namegiscus:backlink content...giscus 在创建新讨论时会用其content作为回链地址而不是默认的window.location.href。这在希望使用短链接、或担心改版后 URL 失效的场景下非常有用。该逻辑对应前端创建讨论时传入的backLinkcomponents/Widget.tsx。与 React / Vue / Svelte 集成对于使用前端框架的开发者README 提示要在 React、Vue 或 Svelte 项目中使用 giscus可以选用giscus 组件库giscus component library。此外仓库还支持通过postMessage与 giscus 的iframe进行双向通信giscus → 父页面错误信息IErrorMessage、讨论元数据IMetadataMessage需开启data-emit-metadata1后周期性地发出且仅在讨论存在时发出父页面 → giscusISetConfigMessage可在不重新加载script/iframe的情况下动态更新主题、仓库、分类、映射词、评论排序、语言等配置所有属性均为可选可只更新子集。这些消息的 TypeScript 接口定义集中在 lib/types/giscus.ts如ISetConfigMessage见 lib/types/giscus.ts前端 pages/widget.tsx 中也实现了对setConfig消息的监听处理可据此验证消息协议的具体字段。自托管Self-hostingREADME 强调 giscus可以自托管。仓库根目录的 SELF-HOSTING.md 是完整的自托管指南需要配置的环境变量集中在 lib/variables.ts主要包括GitHub App 相关的GITHUB_APP_ID、GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET、GITHUB_INSTALLATION_ID、GITHUB_PRIVATE_KEY、GITHUB_TOKEN以及会话加密密钥ENCRYPTION_PASSWORD、对外服务地址NEXT_PUBLIC_GISCUS_APP_HOST、来源白名单ORIGINS/ORIGINS_REGEX等。具体部署步骤如 Vercel 或自建服务器请以该文档为准。迁移指南从 Issues 方案平滑切换README 的 Migrating 章节为存量用户提供了迁移路径如果你此前使用的是基于 GitHub Issues 的评论系统如utterances、gitalk可以把现有的 Issues 转换为 Discussions在 GitHub 讨论管理功能中执行转换。转换完成后只需确认讨论标题与页面之间的映射关系正确giscus 就会自动复用这些讨论无需重新造数据。迁移完成后建议核对每个页面的映射方式URL / pathname / title与对应讨论标题一致如果启用了data-strict1存量讨论正文中需包含标题的 SHA-1 哈希参见上文评论顺序与审核权限符合预期因为评论数据现在属于 GitHub Discussions 的管辖范围。参与贡献与其他说明如果你希望参与 giscus 的开发、翻译或主题创作请查阅 CONTRIBUTING.md。README 中还列出了若干公开使用 giscus 的站点如 laymonage.com、os.phil-opp.com、Stats and R 播客等并在 GitHub 上设有giscus话题供社区发现更多使用者。最后再次提醒README 明确指出 giscus 与 GitHub Discussions 本身都处于活跃演进阶段功能可能变动在使用本指南中的配置项时建议以当前仓库的实际实现与 GitHub 最新 API 文档为准。赞分享后端【免费下载链接】giscusA commenting system powered by GitHub Discussions. :octocat: :speech_balloon: :gem:项目地址https://gitcode.com/gh_mirrors/gi/giscus点击查看免费下载相关推荐giscus 评论系统指南基于 GitHub Discussions 的开源评论组件集成与高级配置giscus 评论系统指南基于 GitHub Discussions 的开源评论组件集成与高级配置 导读 giscus 是一个由 GitHub Discuss后端gs-quant 时间序列经济计量用 prices 函数从收益率序列重建价格水平gs quant 时间序列经济计量用 prices 函数从收益率序列重建价格水平 在量化研究中价格与收益率之间的互相转换是最基础也最高频的操作。gs qua后端giscus 技术全解基于 GitHub Discussions 的开源评论系统原理、配置与迁移实战giscus 技术全解基于 GitHub Discussions 的开源评论系统原理、配置与迁移实战 导读 本文以 giscus 项目官方德语 README后端上一篇IdeaVim sethandler 命令完全指南通过 .ideavimrc 精确配置 Vim 与 IDE 的快捷键冲突下一篇如何快速制作专业学术演示中国科学技术大学Beamer模板终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考