后端【免费下载链接】giscusA commenting system powered by GitHub Discussions. :octocat: :speech_balloon: :gem:项目地址https://gitcode.com/gh_mirrors/gi/giscus点击查看免费下载giscus 是一款完全开源、无需数据库的评论组件它把 GitHub Discussions 直接变成你网站的评论区访客可以用 GitHub 账号发表评论与表情反应评论数据天然沉淀在你的仓库里。本文以仓库官方 README匈牙利语版 README.hu.md内容与英文版 README.md 一致为骨架结合仓库源码与配置系统讲解 giscus 的工作原理、快速接入、仓库级高级配置、宿主页面通信与自托管部署帮助你完整掌握这套评论方案。giscus 是什么核心特性一览giscus 是一个由 GitHub Discussions 驱动的评论系统访客通过 GitHub 在你网站上留下评论和反应所有数据都存储在 GitHub Discussions 中。它的设计深受 [utterances] 启发但与 utterances 基于 GitHub Issues 不同giscus 完全构建在 Discussions 及其 GraphQL API 之上。官方 README 明确列出的核心特性包括开源整个项目以开源形式发布可以自由查看、修改与部署。无追踪、无广告、永久免费不依赖第三方广告与统计服务。无需数据库所有评论数据都存放在 GitHub Discussions 中由 GitHub 负责存储与备份。支持自定义主题内置多套主题并允许通过自定义 CSS 深度定制详见 ADVANCED-USAGE.md 的data-theme一节。支持多语言项目内置数十种语言的界面翻译翻译资源集中在 locales 目录每种语言包含 common.json 与 config.json 两个文件。高度可配置支持从仓库级配置到 script 标签属性的多层级定制。自动同步自动从 GitHub 拉取新的评论与编辑内容无需手动刷新。可自托管可以部署在自己的服务器上详见 SELF-HOSTING.md。注意来自官方 READMEgiscus 仍处于活跃开发阶段GitHub 也在持续演进 Discussions 及其 API因此 giscus 的某些功能可能随时间发生变化或失效。接入时建议关注上游更新。工作原理如何用 GitHub Discussions 承载评论根据 README 的How it works一节giscus 的工作流程可以拆成三个关键环节查找讨论当 giscus 在页面加载时会调用 GitHub Discussions 搜索 API根据你选择的映射方式页面 URL、pathname、title等查找与当前页面关联的 Discussion。自动创建如果找不到匹配的 Discussiongiscus bot 会在访客第一次发表评论或留下反应时自动在对应仓库中创建一条新的 Discussion。身份与授权访客要发表评论必须通过 GitHub OAuth 流程授权 [giscus app] 以访客的名义发帖访客也可以直接到 GitHub 上的 Discussion 里评论而你可以在 GitHub 端对评论进行审核管理。源码层面讨论的查找逻辑集中在 services/github/getDiscussion.ts。它构造 GraphQL 查询时会根据strict参数选择搜索策略const resolvedTerm strict ? await digestMessage(term) : term; const searchIn strict ? in:body : in:title; const query repo:${repo} ${categoryQuery} ${searchIn} ${JSON.stringify(resolvedTerm)};默认情况下以讨论标题作为搜索词在in:title中检索当开启严格模式时则改为在in:body中检索标题的哈希值下文data-strict一节会详细说明。另外该文件还强制将仓库名转为小写以规避 GitHub 在查询中使用 category 时的一个已知问题。返回的讨论数据随后通过 lib/adapter.ts 中的适配函数如adaptDiscussion、adaptComment转换为组件渲染所需的内部数据结构。快速接入与基础配置在 giscus 官网配置页自托管时使用你自己的部署页面选择仓库、映射方式与主题后页面会生成一段script标签把它粘贴到网页中即可完成接入。script 标签上携带的data-属性构成 giscus 的配置面在 lib/types/giscus.ts 的ISetConfigMessage接口中可以看到完整的可配置项repo、repoId、category、categoryId、term、description、backLink、number、strict、reactionsEnabled、emitMetadata、inputPosition、lang、theme。一个典型的接入脚本形如来自 ADVANCED-USAGE.md 的示例script srchttps://giscus.app/client.js >string window.origin只有origins与originsRegex中的任一规则匹配window.origin时giscus 才会加载如果两个列表都为空或未定义则默认允许加载。{ origins: [https://giscus.app] }originsRegex用正则匹配来源域名originsRegex与origins类似但接受的是正则表达式字符串测试方式为new RegExp(pattern).test(window.origin)两者可以组合使用例如本仓库的 giscus.json 同时配置了精确域名与预览环境域名{ origins: [ https://giscus.app, https://giscus.vercel.app ], originsRegex: [ https://giscus-git-([A-z0-9]|-)*giscus\\.vercel\\.app, http://selfhost:[0-9] ], defaultCommentOrder: oldest }底层实现位于 lib/config.ts 的assertOrigin函数它先遍历origins做全等匹配再遍历originsRegex做正则测试任一命中即放行两者皆空则直接返回true。这一机制在自托管场景下尤其重要——你可以用它把 giscus 限制在你自己信任的站点域名内防止他人盗用你的仓库讨论。defaultCommentOrder默认评论排序设置默认评论排序方式取值为oldest从旧到新或newest从新到旧默认值为oldest。对应类型定义见 lib/types/giscus.ts 中的CommentOrder。{ defaultCommentOrder: newest }script 标签的高级>export async function digestMessage(message: string, algorithm: AlgorithmIdentifier SHA-1) { const msgUint8 new TextEncoder().encode(message); const hashBuffer await webcrypto.subtle.digest(algorithm, msgUint8); const hashArray Array.from(new Uint8Array(hashBuffer)); const hashHex hashArray.map((b) b.toString(16).padStart(2, 0)).join(); return hashHex; }在 services/github/getDiscussion.ts 中严格模式下的搜索词即由digestMessage(term)生成。启用该选项时需要确保目标 Discussion 的正文中包含标题的 SHA-1 哈希开启该选项之后由 giscus 新建的 Discussion 会自动附带哈希格式为 HTML 注释因此在 GitHub 页面上不可见!-- sha1: cad60a29d1b50cbeb42ec2ff630fc508afb1d2e3 --对于在此之前已存在的 Discussion可以手动编辑讨论正文把标题的 SHA-1 哈希可用任意 SHA-1 计算器生成写进正文任意位置即可完成迁移。格式不必完全一致只要哈希出现在正文中giscus 就能找到它。data-theme加载自定义主题 CSSdata-theme的值可以是内置主题名也可以是一个CSS 文件的 URL。传入 URL 时giscus 会在head的末尾追加一个link relstylesheet元素来加载该样式script srchttps://giscus.app/client.js >link idgiscus-theme relstylesheet crossoriginanonymous hrefhttps://giscus.app/themes/custom_example.css仓库内置主题的完整清单可见 lib/variables.ts 的availableThemes如light、dark、preferred_color_scheme、transparent_dark、noborder_*、gruvbox、catppuccin_*、cobalt、purple_dark、fro等对应的样式文件存放在 styles/themes 目录其中 custom_example.css 可以作为编写自定义主题的起点。安全提醒来自官方文档加载外部 CSS 文件可能不安全。请确保你信任该 CSS 的作者与提供方如果所使用的 CSS 给网站上的 giscus 用户带来安全漏洞项目不为此负责请务必让你的用户知晓这一点。meta标签定制回链giscus:backlink当 giscus 新建一条 Discussion 时默认会在讨论正文中回链当前页面使用window.location.href。如果你想自定义这个回链地址可以在页面head中加入带namegiscus:backlink的meta标签giscus 会改用其content属性作为回链head !-- ... -- meta namegiscus:backlink contenthttps://bit.ly/RickRolled !-- ... -- /head此时新创建的 Discussion 正文中的链接将是https://bit.ly/RickRolled而不是页面真实 URL。这在你想为页面使用短链接时非常有用——例如网站 URL 结构或域名变更时短链接不会因此失效。与宿主页面通信message 事件giscus 运行在iframe中通过postMessage与宿主页面双向通信对应的消息类型定义在 lib/types/giscus.ts。giscus → 宿主页面iframe 向父窗口发消息giscus 通过window.parent.postMessage()向父窗口发出message事件宿主页面可以监听这些事件并根据 giscus 的状态更新页面function handleMessage(event: MessageEvent) { if (event.origin ! https://giscus.app) return; if (!(typeof event.data object event.data.giscus)) return; const giscusData event.data.giscus; // 例如 console.log(giscusData)注意用 discussion in giscusData 等判断消息类型 } window.addEventListener(message, handleMessage); // 稍后移除监听 window.removeEventListener(message, handleMessage);IErrorMessage默认情况下giscus 遇到错误时会向父窗口发送{ error: string }格式的错误消息。客户端脚本正是利用它自动清理父页面localStorage中失效或过期的会话数据。对大多数用户用处不大但需要时也可以自行接收interface IErrorMessage { error: string; } if (error in giscusData) { const errorMessage: IErrorMessage giscusData; console.error(errorMessage.error); }IMetadataMessage如果在 script 标签上设置data-emit-metadata1giscus 会周期性发送讨论元数据仅在 Discussion 存在时发送interface IMetadataMessage { discussion: IDiscussionData; viewer: IUser; } if (discussion in giscusData) { const metadataMessage: IMetadataMessage giscusData; console.log(metadataMessage.discussion); console.log(metadataMessage.viewer); }IDiscussionData包含讨论的id、url、locked状态、仓库nameWithOwner、反应总数、评论/回复计数等字段见 lib/types/giscus.ts。此外该文件中还定义了IResizeHeightMessageiframe 高度自适应与ISignOutMessage登出等内部消息类型。宿主页面 → giscus父窗口向 iframe 发消息giscusiframe的contentWindow也监听message事件宿主页面可以借此动态更新 giscus 配置而无需重新加载 script 或 iframe 元素function sendMessageT(message: T) { const iframe document.querySelectorHTMLIFrameElement(iframe.giscus-frame); if (!iframe) return; iframe.contentWindow.postMessage({ giscus: message }, https://giscus.app); }ISetConfigMessagesetConfig中的属性全部可选因此你可以只更新部分配置、其余保持原样。例如动态切换主题并关闭反应功能interface ISetConfigMessage { setConfig: { theme?: Theme; repo?: string; repoId?: string; category?: string; categoryId?: string; term?: string; description?: string; backLink?: string; number?: number; strict?: boolean; reactionsEnabled?: boolean; emitMetadata?: boolean; inputPosition?: InputPosition; lang?: AvailableLanguage; }; } sendMessage({ setConfig: { theme: https://giscus.app/themes/custom_example.css, reactionsEnabled: false, } });InputPositiontop | bottom、CommentOrderoldest | newest等类型均定义于 lib/types/giscus.ts。从 utterances / gitalk 迁移如果你之前使用过基于 GitHub Issues 的评论系统例如 [utterances]、[gitalk]可以无缝迁移到 giscus先在 GitHub 端把已有的 Issues转换为 Discussions转换后只需确保讨论标题与页面之间的映射关系正确标题要与页面 URL、pathname 或 title 等映射方式对应giscus 便会自动使用这些已有讨论而不会重复创建。转换操作在 GitHub 的 Discussion 管理界面完成。自托管部署官方 README 指出 giscus 可以自行部署详见 SELF-HOSTING.md。自托管的核心步骤包括创建 GitHub App在 GitHub 的 App 创建页面注册新应用。授权回调 URL 必须设置为https://[你的域名]/api/oauth/authorized对应本仓库 pages/api/oauth/authorized.ts 路由。不要勾选Expire user authorization tokensgiscus 目前不支持令牌过期如确有需求可修改代码中的TOKEN_VALIDITY_PERIOD来定期吊销用户令牌。Webhook 不需要取消勾选Active。仓库权限只需为Discussions开启 Read write其余保持默认。生成凭据生成私钥private key、生成并保存 client secret、复制 App ID 与 Client ID。安装 App在侧边栏进入 Install App 并安装到你的账号。建议选择 Only select repositories 并指定仓库若选择 All repositoriesApp 将能访问包括私有仓库在内的所有讨论任何知道仓库名的人都能读取和发帖务必谨慎。可选配置 Supabase 缓存令牌GitHub App 的安装访问令牌 TTL 只有 60 分钟可以在 Supabase 中建表缓存令牌以减少向 GitHub 的令牌请求次数、避免触发限流。默认表名为installation_access_tokensschema 包含installation_idint8主键、tokenvarchar、expires_attimestamptz、created_attimestamptz默认NOW()、updated_attimestamptz默认NOW()各列均不可为空同时需关闭表的 RLS 或使用service_role密钥。部署应用giscus 官网托管在 Vercel 上但任何能运行 Next.js 应用及 serverless 函数的平台都可以部署。流程为克隆仓库 → 设置环境变量 →yarn install→yarn build→yarn start。所需环境变量的完整清单见 lib/variables.ts包括GITHUB_APP_ID、GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET、GITHUB_INSTALLATION_ID、GITHUB_PRIVATE_KEY、ENCRYPTION_PASSWORD用于加密用户令牌的随机字符串、NEXT_PUBLIC_GISCUS_APP_HOST以及可选的 Supabase/Valkey 缓存相关变量。使用自托管实例在自托管站点的配置页生成 script 配置如data-repo-id、data-category-id并确保网页引用的是你的部署所托管的 client.js。另外README 还提到若要使用 React、Vue 或 Svelte 集成可以关注 giscus 的组件库相关用法可进一步参考仓库文档。多语言、使用案例与贡献多语言giscus 界面支持数十种语言翻译文件位于 locales每种语言一个目录含common.json与config.jsonREADME 本身也提供了多种语言版本如 README.zh-CN.md、README.de.md、README.fr.md 等匈牙利语版即为本文依据的 README.hu.md。使用案例官方 README 中专门有一节列举使用 giscus 的网站包括 laymonage.com、os.phil-opp.com、Stats and R、Tech Debt Burndown Podcast 等涵盖个人博客与技术文档站点。贡献欢迎参与贡献具体指引见 CONTRIBUTING.md如果正在使用 giscus官方也建议在 GitHub 上为项目加星标。结语giscus 的整套设计遵循复用 GitHub 生态的思路评论存储、身份认证、内容审核、数据备份全部交由 GitHub 完成你只需维护一段脚本与一份可选的仓库配置。结合本仓库源码你可以进一步阅读 lib/types/giscus.ts 理解消息协议、通过 lib/config.ts 掌握 origin 校验逻辑、在 services/github 中追踪完整的 GitHub GraphQL 调用链从而在接入、定制乃至自托管时做到心中有数。赞分享后端【免费下载链接】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后端Caveman Skill 模式选型指南/caveman 六档 token 压缩 3 分钟上手Caveman Skill 模式选型指南/caveman 六档 token 压缩 3 分钟上手 Caveman Skill 给编码代理注入一套规则让 AI人工智能AI 应用AI 技能AI 插件LLMOps开发工具如何为你的平衡车升级FOC场定向控制终极性能提升指南如何为你的平衡车升级FOC场定向控制终极性能提升指南 你是否厌倦了平衡车电机刺耳的噪音和振动想不想让电动滑板或轮椅驱动系统运行更平稳、更高效今天我要为你介后端上一篇如何上手 Maccy1 行命令搞定的 macOS 剪贴板管理指南下一篇unlock-music浏览器解锁15种加密音乐创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考