如何将 Giscus 评论集成到 AstroPaper

在 GitHub Pages 等平台上托管轻量级静态博客有很多优势，但也失去了一些交互性。幸运的是，Giscus 的存在提供了一种在静态网站上嵌入用户评论的方法。

Giscus 的工作原理

Giscus 使用 GitHub API 来读取和存储 GitHub 用户在与仓库关联的 Discussions 中发表的评论。

在你的网站上嵌入 Giscus 客户端脚本包，使用正确的仓库 URL 进行配置，用户就可以查看和撰写评论（当登录到 GitHub 时）。

这种方法是无服务器的，因为评论存储在 GitHub 上，并在客户端动态加载，因此非常适合像 AstroPaper 这样的静态博客。

设置 Giscus

Giscus 可以在 giscus.app 上轻松设置，但我还是会简要概述这个过程。

前提条件

让 Giscus 工作的前提条件是：

仓库是公开的
已安装 Giscus 应用
为你的仓库启用了 Discussions 功能

如果由于任何原因无法满足这些条件中的任何一个，不幸的是，Giscus 无法集成。

配置 Giscus

接下来，需要配置 Giscus。在大多数情况下，预选的默认值是合适的，只有在你有特定原因并且知道自己在做什么时才应该修改它们。不要太担心做出错误的选择；你随时可以调整配置。

但是你需要：

为 UI 选择正确的语言
指定你想要连接的 GitHub 仓库，通常是包含你在 GitHub Pages 上静态托管的 AstroPaper 博客的仓库
如果你想确保没有人可以直接在 GitHub 上创建随机评论，请在 GitHub 上创建并设置一个 Announcement 类型的讨论
定义配色方案

配置设置后，Giscus 会为你提供一个生成的 <script> 标签，你将在接下来的步骤中需要它。

简单的脚本标签

你现在应该有一个看起来像这样的脚本标签：

<script
  src="https://giscus.app/client.js"
  data-repo="[在此输入仓库]"
  data-repo-id="[在此输入仓库 ID]"
  data-category="[在此输入分类名称]"
  data-category-id="[在此输入分类 ID]"
  data-mapping="pathname"
  data-strict="0"
  data-reactions-enabled="1"
  data-emit-metadata="0"
  data-input-position="bottom"
  data-theme="preferred_color_scheme"
  data-lang="zh-CN"
  crossorigin="anonymous"
  async
></script>

只需将其添加到网站的源代码中。很可能，如果你使用 AstroPaper 并想在文章上启用评论，请导航到 PostDetails.astro 并将其粘贴到你希望评论出现的位置，也许在 分享这篇文章： 按钮下方。

<Layout {...layoutProps}>
  <main>
    <ShareLinks />

    <!-- [!code ++:6] -->
    <script
      src="https://giscus.app/client.js"
      data-repo="[在此输入仓库]"
      data-repo-id="[在此输入仓库 ID]"
      data-category="[在此输入分类名称]"
      data-category-id="[在此输入分类 ID]"></script>
  </main>
  <Footer />
</Layout>

完成了！你已经成功地在 AstroPaper 中集成了评论！

带有明暗主题的 React 组件

布局中嵌入的脚本标签相当静态，Giscus 配置（包括 theme）被硬编码到布局中。鉴于 AstroPaper 具有明暗主题切换功能，如果评论能够与网站的其余部分一起在明暗主题之间无缝过渡就更好了。要实现这一点，需要一种更复杂的嵌入 Giscus 的方法。

首先，我们将安装 Giscus 的 React 组件：

npm i @giscus/react && npx astro add react

然后我们在 src/components 中创建一个新的 Comments.tsx React 组件：

import Giscus, { type Theme } from "@giscus/react";
import { GISCUS } from "@/constants";
import { useEffect, useState } from "react";

interface CommentsProps {
  lightTheme?: Theme;
  darkTheme?: Theme;
}

export default function Comments({
  lightTheme = "light",
  darkTheme = "dark",
}: CommentsProps) {
  const [theme, setTheme] = useState(() => {
    const currentTheme = localStorage.getItem("theme");
    const browserTheme = window.matchMedia("(prefers-color-scheme: dark)")
      .matches
      ? "dark"
      : "light";

    return currentTheme || browserTheme;
  });

  useEffect(() => {
    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
    const handleChange = ({ matches }: MediaQueryListEvent) => {
      setTheme(matches ? "dark" : "light");
    };

    mediaQuery.addEventListener("change", handleChange);

    return () => mediaQuery.removeEventListener("change", handleChange);
  }, []);

  useEffect(() => {
    const themeButton = document.querySelector("#theme-btn");
    const handleClick = () => {
      setTheme(prevTheme => (prevTheme === "dark" ? "light" : "dark"));
    };

    themeButton?.addEventListener("click", handleClick);

    return () => themeButton?.removeEventListener("click", handleClick);
  }, []);

  return (
    <div className="mt-8">
      <Giscus theme={theme === "light" ? lightTheme : darkTheme} {...GISCUS} />
    </div>
  );
}

这个 React 组件不仅包装了原生的 Giscus 组件，还引入了额外的 props，即 lightTheme 和 darkTheme。利用两个事件监听器，Giscus 评论将与网站的主题保持一致，每当网站或浏览器主题更改时，都会在深色和浅色主题之间动态切换。

我们还需要定义 GISCUS 配置，最佳位置是在 constants.ts 中：

import type { GiscusProps } from "@giscus/react";

...

export const GISCUS: GiscusProps = {
  repo: "[在此输入仓库]",
  repoId: "[在此输入仓库 ID]",
  category: "[在此输入分类名称]",
  categoryId: "[在此输入分类 ID]",
  mapping: "pathname",
  reactionsEnabled: "0",
  emitMetadata: "0",
  inputPosition: "bottom",
  lang: "zh-CN",
  loading: "lazy",
};

请注意，在这里指定 theme 将覆盖 lightTheme 和 darkTheme props，导致静态主题设置，类似于之前使用 <script> 标签嵌入 Giscus 的方法。

要完成该过程，请将新的 Comments 组件添加到 PostDetails.astro（替换上一步中的 script 标签）。

// [!code ++:1]
import Comments from "@/components/Comments";

<ShareLinks />

// [!code ++:1]
<Comments client:only="react" />

<hr class="my-6 border-dashed" />

<Footer />

就是这样！