Giscus 在 Astro 中自动更换主题颜色#

在构建现代博客时，添加评论系统是提高用户互动的重要方式。Giscus 是一个基于 GitHub Discussions 的评论系统，它完全开源、无广告，并且可以很好地集成到静态网站中。然而，当我们的网站支持深色和浅色主题切换时，评论区的主题也应该相应变化，以保持整体视觉体验的一致性。

本文将介绍如何在 Astro 框架中实现 Giscus 评论系统的自动主题切换功能。

为什么选择 Giscus？#

与其他评论系统相比，Giscus 具有以下优势：

基于 GitHub Discussions：所有评论都存储在 GitHub 上，无需额外数据库
完全开源：代码透明，可自由定制
无广告：提供干净的用户体验
支持多种主题：包括浅色和深色模式
支持 Markdown：评论支持 Markdown 格式

实现步骤#

1. 创建 Giscus 组件#

首先，我们需要在 Astro 项目中创建一个 Giscus 组件。这个组件将负责加载 Giscus 脚本并处理主题切换。

创建文件 src/components/comments/Giscus.astro：

1
---
2
import I18nKey from "../../i18n/i18nKey";
3
import { i18n } from "../../i18n/translation";
4
---
5

6
<div class="card-base p-6 md:p-8 mb-4 w-full onload-animation">
7
    <h2 class="text-2xl font-bold mb-6 text-black/90 dark:text-white/90">{i18n(I18nKey.comments)}</h2>
8

9
    <div id="giscus-container" class="giscus-wrapper">
10
        <!-- 在这里我们将动态插入 Giscus 脚本 -->
11
    </div>
12
</div>
13

14
<script is:inline>
15
    // 立即执行函数，确保尽早运行
16
    (function() {
17
        // 检测当前主题模式并返回对应的 Giscus 主题
18
        function getGiscusTheme() {
19
            return document.documentElement.classList.contains('dark') ? 'dark_tritanopia' : 'fro';
20
        }
21

22
        // 创建并插入 Giscus 脚本
23
        function createGiscusScript() {
24
            const theme = getGiscusTheme();
25
            const script = document.createElement('script');
26

27
            script.src = 'https://giscus.app/client.js';
28
            script.setAttribute('data-repo', '您的仓库名');
29
            script.setAttribute('data-repo-id', '您的仓库ID');
30
            script.setAttribute('data-category', 'Announcements');
31
            script.setAttribute('data-category-id', '分类ID');
32
            script.setAttribute('data-mapping', 'pathname');
33
            script.setAttribute('data-strict', '0');
34
            script.setAttribute('data-reactions-enabled', '1');
35
            script.setAttribute('data-emit-metadata', '0');
36
            script.setAttribute('data-input-position', 'top');
37
            script.setAttribute('data-theme', theme);
38
            script.setAttribute('data-lang', 'zh-CN');
39
            script.setAttribute('data-loading', 'lazy');
40
            script.setAttribute('crossorigin', 'anonymous');
41
            script.async = true;
42

43
            return script;
44
        }
45

46
        // 监听主题变化
47
        function setupThemeObserver() {
48
            const observer = new MutationObserver((mutations) => {
49
                mutations.forEach((mutation) => {
50
                    if (mutation.attributeName === 'class' &&
51
                        mutation.target === document.documentElement) {
52
                        updateGiscusTheme();
53
                    }
54
                });
55
            });
56

57
            observer.observe(document.documentElement, { attributes: true });
58
        }
59

60
        // 更新 Giscus 主题
61
        function updateGiscusTheme() {
62
            const theme = getGiscusTheme();
63

64
            const iframe = document.querySelector('iframe.giscus-frame');
65
            if (iframe && 'contentWindow' in iframe) {
66
                iframe.contentWindow.postMessage(
67
                    { giscus: { setConfig: { theme } } },
68
                    'https://giscus.app'
69
                );
70
            }
71
        }
72

73
        // 初始化 Giscus
74
        function initGiscus() {
75
            const container = document.getElementById('giscus-container');
76
            if (container) {
77
                // 清空容器（防止重复加载）
78
                container.innerHTML = '';
79
                // 添加脚本
80
                container.appendChild(createGiscusScript());
81
                // 设置主题观察器
82
                setupThemeObserver();
83
            }
84
        }
85

86
        // 尝试立即加载
87
        if (document.readyState === 'loading') {
88
            document.addEventListener('DOMContentLoaded', initGiscus);
89
        } else {
90
            // 如果 DOM 已经加载完成，立即执行
91
            initGiscus();
92
        }
93

94
        // 确保在页面完全加载后也能正常初始化（双重保险）
95
        window.addEventListener('load', initGiscus);
96
    })();
97
</script>
98

99
<style>
100
    .giscus-wrapper {
101
        width: 100%;
102
    }
103
</style>

注意：上面的代码中，您需要将 data-repo、data-repo-id 和 data-category-id 替换为您自己的值。这些值可以从 Giscus 官网获取。

2. 代码解析#

让我们详细解释一下这个组件的工作原理：

主题检测和设置#

1
function getGiscusTheme() {
2
    return document.documentElement.classList.contains('dark') ? 'dark_tritanopia' : 'fro';
3
}

这个函数检查文档的根元素是否包含 dark 类来判断当前主题。如果是深色模式，则返回 dark_tritanopia 主题；否则返回 fro 主题。

动态创建 Giscus 脚本#

1
function createGiscusScript() {
2
    const theme = getGiscusTheme();
3
    const script = document.createElement('script');
4

5
    // 设置 Giscus 属性...
6

7
    return script;
8
}

这个函数动态创建 Giscus 脚本元素，并根据当前主题设置适当的 data-theme 属性。

监听主题变化#

1
function setupThemeObserver() {
2
    const observer = new MutationObserver((mutations) => {
3
        mutations.forEach((mutation) => {
4
            if (mutation.attributeName === 'class' &&
5
                mutation.target === document.documentElement) {
6
                updateGiscusTheme();
7
            }
8
        });
9
    });
10

11
    observer.observe(document.documentElement, { attributes: true });
12
}

使用 MutationObserver 监听文档根元素的 class 属性变化。当检测到变化时，调用 updateGiscusTheme() 函数更新 Giscus 主题。

更新 Giscus 主题#

1
function updateGiscusTheme() {
2
    const theme = getGiscusTheme();
3

4
    const iframe = document.querySelector('iframe.giscus-frame');
5
    if (iframe && 'contentWindow' in iframe) {
6
        iframe.contentWindow.postMessage(
7
            { giscus: { setConfig: { theme } } },
8
            'https://giscus.app'
9
        );
10
    }
11
}

这个函数通过 postMessage API 向 Giscus iframe 发送消息，告知其更新主题。

初始化和加载保障#

1
// 尝试立即加载
2
if (document.readyState === 'loading') {
3
    document.addEventListener('DOMContentLoaded', initGiscus);
4
} else {
5
    // 如果 DOM 已经加载完成，立即执行
6
    initGiscus();
7
}
8

9
// 确保在页面完全加载后也能正常初始化（双重保险）
10
window.addEventListener('load', initGiscus);

这部分代码确保 Giscus 在以下情况下都能正确初始化：

脚本在 DOM 加载前执行
脚本在 DOM 加载后执行
页面完全加载后（作为备份机制）

使用方法#

将 Giscus 组件添加到您的文章模板或布局中，例如：

1
---
2
// 其他导入...
3
import Giscus from '../components/comments/Giscus.astro';
4
---
5

6
<Layout>
7
  <article>
8
    <!-- 文章内容 -->
9
  </article>
10

11
  <Giscus />
12
</Layout>

常见问题及解决方案#

1. 首次加载时主题不匹配#

有时候，当页面首次加载时，Giscus 可能会使用默认主题而不是当前网站主题。这通常是因为 Giscus 脚本在检测到正确主题之前就已加载。

解决方案：我们的代码中已经通过立即执行函数和多重加载检查解决了这个问题。

2. 主题切换后 Giscus 不更新#

如果在切换网站主题后 Giscus 主题没有更新，可能是因为 MutationObserver 没有正确设置或者 postMessage 调用有问题。

解决方案：确保 MutationObserver 正确监听了文档根元素的类变化，并且 postMessage 调用格式正确。

3. Giscus 重复加载#

在某些情况下，特别是使用 SPA 路由时，Giscus 可能会重复加载。

解决方案：在我们的代码中，通过在添加新的 Giscus 脚本前清空容器内容（container.innerHTML = '';）解决了这个问题。

结论#

通过以上方法，我们成功实现了 Giscus 评论系统在 Astro 中随网站主题自动切换的功能。这不仅提升了用户体验，也保持了整个网站视觉风格的一致性。

Giscus 作为一个基于 GitHub Discussions 的评论系统，为静态网站提供了一个轻量级、无广告的评论解决方案。结合 Astro 的强大功能，我们可以创建一个既美观又实用的博客系统。