前言#

TIP
在 Mizuki 主题 9.0 版本默认已集成 Giscus 评论系统，本文适用于旧版本手动集成。

Mizuki 主题默认使用 Twikoo 作为评论系统。Giscus 基于 GitHub Discussions，无需数据库、无第三方服务依赖，且支持 Markdown 和代码高亮。本文介绍如何在旧版 Mizuki 主题中手动集成 Giscus。

准备工作#

1. 创建评论仓库#

在 GitHub 新建一个 公开（public） 仓库，用于存储评论数据。
进入仓库 Settings → General，在 Features 区域勾选 Discussions 并保存。

2. 获取 Giscus 配置#

访问 giscus.app，按向导完成配置。完成后会生成如下代码，记下其中的关键参数：

1
<script src="https://giscus.app/client.js"
2
  data-repo="your-github-username/your-repo-name"
3
  data-repo-id="your-repo-id"
4
  data-category="Announcements"
5
  data-category-id="your-category-id"
6
  data-mapping="pathname"
7
  data-strict="0"
8
  data-reactions-enabled="1"
9
  data-emit-metadata="0"
10
  data-input-position="top"
11
  data-theme="preferred_color_scheme"
12
  data-lang="zh-CN"
13
  data-loading="lazy"
14
  crossorigin="anonymous"
15
  async>
16
</script>

修改主题配置#

1. 更新评论配置#

编辑 src/config.ts，将 Twikoo 配置替换为 Giscus：

1
export const commentConfig: CommentConfig = {
2
  enable: false,
3
  twikoo: {
4
    envId: "https://twikoo.vercel.app",
5
    lang: "en",
6
  },
7
  enable: true,
8
  giscus: {
9
    enable: true,
10
    repo: "your-github-username/your-repo-name",
11
    repoId: "your-repo-id",
12
    category: "Announcements",
13
    categoryId: "your-category-id",
14
    mapping: "pathname",
15
    strict: "0",
16
    reactionsEnabled: "1",
17
    emitMetadata: "0",
18
    inputPosition: "top",
19
    theme: "preferred_color_scheme",
20
    lang: "zh-CN",
21
  },
22
};

2. 添加 Giscus 组件#

在 src/components/comment/ 目录下新建 Giscus.astro（可删除原 Twikoo.astro）：

1
---
2
import { commentConfig } from "@/config";
3

4
interface Props {
5
  path: string;
6
}
7

8
const giscusConfig = commentConfig.giscus;
9
---
10

11
<div class="giscus-container"></div>
12

13
<script is:inline define:vars={{ giscusConfig }}>
14
  (() => {
15
    const getTheme = () => document.documentElement.classList.contains('dark') ? 'dark' : 'light';
16

17
    const loadGiscus = () => {
18
      const root = document.querySelector('.giscus-container');
19
      if (!root || root.querySelector('iframe.giscus-frame')) return;
20

21
      const s = document.createElement('script');
22
      s.src = 'https://giscus.app/client.js';
23
      s.async = true;
24

25
      Object.entries({
26
        'data-repo': giscusConfig.repo,
27
        'data-repo-id': giscusConfig.repoId,
28
        'data-category': giscusConfig.category,
29
        'data-category-id': giscusConfig.categoryId,
30
        'data-mapping': giscusConfig.mapping || 'pathname',
31
        'data-strict': giscusConfig.strict || '0',
32
        'data-reactions-enabled': giscusConfig.reactionsEnabled || '1',
33
        'data-emit-metadata': giscusConfig.emitMetadata || '0',
34
        'data-input-position': giscusConfig.inputPosition || 'top',
35
        'data-lang': giscusConfig.lang || 'zh-CN',
36
        'data-loading': 'lazy',
37
        'data-theme': getTheme()
38
      }).forEach(([key, value]) => s.setAttribute(key, value));
39

40
      root.appendChild(s);
41
    };
42

43
    const updateTheme = () => {
44
      const iframe = document.querySelector('iframe.giscus-frame');
45
      if (iframe?.contentWindow) {
46
        iframe.contentWindow.postMessage({ giscus: { setConfig: { theme: getTheme() } } }, 'https://giscus.app');
47
      }
48
    };
49

50
    loadGiscus();
51

52
    if (!window._giscusObserver) {
53
      const observer = new MutationObserver((mutations) => {
54
        if (mutations.some(m => m.type === 'attributes' && m.attributeName === 'class')) {
55
          updateTheme();
56
        }
57
      });
58
      observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] });
59
      window._giscusObserver = observer;
60
    }
61

62
    const handleSwup = () => loadGiscus();
63
    if (window.swup) {
64
      window.swup.hooks.on('content:replace', handleSwup);
65
    } else {
66
      document.addEventListener('swup:enable', () => {
67
        window.swup?.hooks.on('content:replace', handleSwup);
68
      }, { once: true });
69
    }
70
  })();
71
</script>
72

73
<style>
74
  .giscus-container {
75
    width: 100%;
76
    margin-top: 1rem;
77
    transition: color 0.15s, background-color 0.15s, border-color 0.15s;
78
  }
79
  .giscus-container iframe.giscus-frame {
80
    width: 100% !important;
81
    border-radius: var(--radius-large);
82
    border: 1px solid var(--line-divider);
83
    background: transparent;
84
    transition: border-color 0.15s, background-color 0.15s;
85
  }
86
  .giscus-container:hover iframe.giscus-frame {
87
    border-color: var(--primary);
88
  }
89
  :root:not(.dark) .giscus-container {
90
    color-scheme: light;
91
  }
92
  :root.dark .giscus-container {
93
    color-scheme: dark;
94
  }
95
</style>

3. 更新评论组件入口#

编辑 src/components/comment/index.astro：

1
import Twikoo from "./Twikoo.astro";
2
import Giscus from "./Giscus.astro";
3

4
if (commentConfig?.enable && commentConfig?.twikoo) {
5
  commentService = "twikoo";
6
if (commentConfig?.enable) {
7
  if (commentConfig?.giscus) {
8
    commentService = "giscus";
9
  }
10

11
{commentService === 'twikoo' && <Twikoo path={path} />}
12
{commentService === 'giscus' && <Giscus path={path} />}

4. 添加类型定义#

编辑 src/types/config.ts，补充 Giscus 类型：

1
twikoo?: TwikooConfig;
2
giscus?: GiscusConfig;
3

4
type TwikooConfig = {
5
  envId: string;
6
  region?: string;
7
};
8
type GiscusConfig = {
9
  enable: boolean;
10
  repo: string;
11
  repoId: string;
12
  category: string;
13
  categoryId: string;
14
  mapping?: string;
15
  strict?: string;
16
  reactionsEnabled?: string;
17
  emitMetadata?: string;
18
  inputPosition?: string;
19
  theme?: string;
20
  lang?: string;
21
};