Mizuki实现Giscus评论区 - SuzuhaYuki's Blog

SuzuhaYuki

统计加载中...

标签

1023 字

5 分钟

Mizuki实现Giscus评论区

2025-09-13

2025-12-05

技术

Mizuki

/

Giscus

统计加载中...

准备工作#

创建 GitHub 仓库
- 新建一个 公开（public） 的 GitHub 仓库。
- 在仓库设置中 启用 Discussions 功能。
生成 Giscus 配置代码
- 访问 giscus官网，根据你的需求完成配置。
- 配置完成后，复制生成的 <script> 代码块，例如：

1
<script src="https://giscus.app/client.js"
2
  data-repo="Leaf-0w0/blog-giscus"
3
    data-repo-id="***"
4
    data-category="Announcements"
5
    data-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>

配置 Mizuki 主题#

1. 修改评论配置文件#

打开 src/config.ts，将原有的 Twikoo 配置替换为 Giscus 配置：
原内容：

1
export const commentConfig: CommentConfig = {
2
  enable: false, // 启用评论功能。当设置为 false 时，评论组件将不会显示在文章区域。
3
  twikoo: {
4
    envId: "https://twikoo.vercel.app",
5
    lang: "en", // 设置 Twikoo 评论系统语言为英文
6
  },
7
};

修改为：

1
export const commentConfig: CommentConfig = {
2
  enable: true, // 启用评论功能。当设置为 false 时，评论组件将不会显示在文章区域。
3
  giscus: {
4
    enable: true,
5
    repo: "Leaf-0w0/blog-giscus",
6
    repoId: "***",
7
    category: "Announcements",
8
    categoryId: "***",
9
    mapping: "pathname",
10
    strict: "0",
11
    reactionsEnabled: "1",
12
    emitMetadata: "0",
13
    inputPosition: "top",
14
    theme: "preferred_color_scheme",
15
    lang: "zh-CN",
16
  },
17
};

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
  (function () {
15
    // 配置项
16
    const CONFIG = {
17
      ...giscusConfig,
18
      mapping: giscusConfig.mapping || 'pathname',
19
      strict: giscusConfig.strict || '0',
20
      reactionsEnabled: giscusConfig.reactionsEnabled || '1',
21
      emitMetadata: giscusConfig.emitMetadata || '0',
22
      inputPosition: giscusConfig.inputPosition || 'top',
23
      lang: giscusConfig.lang || 'zh-CN',
24
      loading: 'lazy'
25
    };
26

27
    // 获取当前主题
28
    function getTheme() {
29
      return document.documentElement.classList.contains('dark') ? 'dark' : 'light';
30
    }
31

32
    // 向 Giscus iframe 发送消息更新配置
33
    function updateGiscusTheme() {
34
      const iframe = document.querySelector('iframe.giscus-frame');
35
      if (!iframe || !iframe.contentWindow) return;
36

37
      const theme = getTheme();
38
      iframe.contentWindow.postMessage(
39
        { giscus: { setConfig: { theme: theme } } },
40
        'https://giscus.app'
41
      );
42
    }
43

44
    // 注入 Giscus 脚本
45
    function loadGiscus() {
46
      const root = document.querySelector('.giscus-container');
47
      // 如果容器不存在，或者已经有 iframe 了，则不处理
48
      if (!root || root.querySelector('iframe.giscus-frame')) return;
49

50
      // 如果已有旧的 script 标签（Swup 切换可能导致残留），先清理
51
      const oldScript = document.getElementById('giscus-script');
52
      if (oldScript) oldScript.remove();
53

54
      const theme = getTheme();
55
      const script = document.createElement('script');
56

57
      script.id = 'giscus-script';
58
      script.src = 'https://giscus.app/client.js';
59
      script.async = true;
60

61
      // 设置核心参数
62
      script.setAttribute('data-repo', CONFIG.repo);
63
      script.setAttribute('data-repo-id', CONFIG.repoId);
64
      script.setAttribute('data-category', CONFIG.category);
65
      script.setAttribute('data-category-id', CONFIG.categoryId);
66
      script.setAttribute('data-mapping', CONFIG.mapping);
67
      script.setAttribute('data-strict', CONFIG.strict);
68
      script.setAttribute('data-reactions-enabled', CONFIG.reactionsEnabled);
69
      script.setAttribute('data-emit-metadata', CONFIG.emitMetadata);
70
      script.setAttribute('data-input-position', CONFIG.inputPosition);
71
      script.setAttribute('data-lang', CONFIG.lang);
72
      script.setAttribute('data-loading', CONFIG.loading);
73

74
      // 关键：直接设置当前主题，无需加载后回调
75
      script.setAttribute('data-theme', theme);
76

77
      root.appendChild(script);
78
    }
79

80
    // 监听 html class 变化（主题切换）
81
    // 只有当 observer 不存在时才创建，防止多重绑定
82
    if (!window._giscusObserver) {
83
      const observer = new MutationObserver((mutations) => {
84
        mutations.forEach((mutation) => {
85
          if (mutation.type === 'attributes' && mutation.attributeName === 'class') {
86
            updateGiscusTheme();
87
          }
88
        });
89
      });
90

91
      observer.observe(document.documentElement, { attributes: true });
92
      window._giscusObserver = observer;
93
    }
94

95
    // 初始化逻辑
96
    function init() {
97
      loadGiscus();
98
    }
99

100
    // 立即执行一次
101
    if (document.readyState === 'loading') {
102
      document.addEventListener('DOMContentLoaded', init);
103
    } else {
104
      init();
105
    }
106

107
    // Swup 适配逻辑
108
    // 使用一个标志位或检查是否已绑定，避免 script 重新执行导致的多重绑定
109
    if (window.swup && !window._giscusSwupListenerAdded) {
110
      const handleSwup = () => {
111
        // Swup 替换内容后，DOM 里的 iframe 会消失，需要重新 load
112
        init();
113
      };
114

115
      window.swup.hooks.on('content:replace', handleSwup);
116
      window.swup.hooks.on('page:view', handleSwup);
117
      window._giscusSwupListenerAdded = true;
118
    } else if (!window.swup && typeof document !== 'undefined') {
119
      // 针对 Swup 还没加载完成的边缘情况
120
      document.addEventListener('swup:enable', () => {
121
         if (window.swup && !window._giscusSwupListenerAdded) {
122
            window.swup.hooks.on('content:replace', init);
123
            window.swup.hooks.on('page:view', init);
124
            window._giscusSwupListenerAdded = true;
125
         }
126
      }, { once: true }); // 仅执行一次
127
    }
128
  })();
129
</script>
130

131
<style>
132
  .giscus-container {
133
    width: 100%;
134
    margin-top: 1rem;
135
    min-height: 200px; /* 防止加载时高度塌陷带来的布局抖动 */
136
    transition: opacity 0.3s;
137
  }
138

139
  .giscus-container iframe.giscus-frame {
140
    width: 100%;
141
    border-radius: var(--radius-large, 8px); /* 提供 fallback */
142
    border: 1px solid var(--line-divider, rgba(0,0,0,0.1));
143
    background: transparent;
144
    transition: border-color 0.15s;
145
  }
146

147
  .giscus-container:hover iframe.giscus-frame {
148
    border-color: var(--primary, #3b82f6);
149
  }
150
</style>

3. 更新评论组件入口#

编辑 src/components/comment/index.astro，替换 Twikoo 相关引用：
原内容：

1
import Twikoo from "./Twikoo.astro"; //文件内第4行
2

3
if (commentConfig?.enable && commentConfig?.twikoo) { //文件内第16行
4
  commentService = "twikoo"; //文件内第17行
5

6
{commentService === 'twikoo' && <Twikoo path={path} />} //文件内第22行

修改为：

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

3
if (commentConfig?.enable) {
4
  if (commentConfig?.giscus) {
5
    commentService = "giscus";
6
  }
7

8
{commentService === 'giscus' && <Giscus path={path} />}

4. 更新类型定义#

在 src/types/config.ts 中，将 Twikoo 类型替换为 Giscus 类型：
原内容：

1
twikoo?: TwikooConfig; //文件内第134行
2

3
type TwikooConfig = { //文件内第137行
4
  envId: string; //文件内第138行
5
  region?: string; //文件内第139行

修改为：

1
giscus?: GiscusConfig;
2

3
type GiscusConfig = {
4
  enable: boolean;
5
  repo: string;
6
  repoId: string;
7
  category: string;
8
  categoryId: string;
9
  mapping?: string;
10
  strict?: string;
11
  reactionsEnabled?: string;
12
  emitMetadata?: string;
13
  inputPosition?: string;
14
  theme?: string;