评论系统

Mizuki 通过统一的 Comment 组件为文章页与自定义页面提供评论能力，底层支持 Twikoo（自托管/云函数后端）与 Giscus（基于 GitHub Discussions）两种评论引擎，可按需二选一，默认关闭。

Purpose and Scope

本页覆盖评论系统这个端到端能力的全部实现环节：

配置层：commentConfig.ts 中的全局开关、引擎选择、Twikoo/Giscus 各自的参数。
组件层：src/components/comment/index.astro 的统一入口、服务选择逻辑与文章级开关；Twikoo.astro 的懒加载与 Swup 兼容实现。
调用层：文章页（posts/[...slug].astro、[...permalink].astro）与自定义页（about.astro、friends.astro）的接入方式。

不属于本页的内容：站点的整体配置合并与覆盖机制（overrides/ 深合并、pnpm export-config）属于站点配置体系的主题，本页仅在"语言覆盖坑"小节引用其结论；音乐播放器、壁纸特效等其它站点服务各有独立页面。

Overview

评论系统是一个静态站点（SSG）+ 外部评论后端的混合架构：Astro 在构建期只输出评论容器与一段引导脚本，真正的评论数据、登录态与存储都由第三方评论服务承载。这种设计让静态博客在不引入数据库的前提下获得完整的评论功能。

关键概念：

概念	说明
评论引擎（system）	`"twikoo"` 或 `"giscus"`，全局唯一，由 `commentConfig.system` 决定
挂载路径（path）	评论串的唯一标识：文章页由 `post.id` 派生为 `/posts/<id>`，自定义页由调用方显式传入
文章级开关	frontmatter 的 `comment` 字段可单独关闭某篇文章的评论，缺省视为开启
懒加载	Twikoo 脚本仅在评论容器进入视口（提前 200px）后才注入并初始化
Swup 兼容	站点使用 Swup 做 SPA 式导航，评论组件监听 `content:replace` 钩子在换页后重新挂载

评论默认关闭（enable: false），使用前需在 src/config/commentConfig.ts 中显式启用并配置对应服务（见各 README 的配置说明）。

Architecture

Loading diagram...

架构分四层，职责边界清晰：

配置层：commentConfig.ts 在模块顶层从 siteConfig.ts 导入 SITE_LANG 填充两个引擎的 lang 字段，保证评论界面语言与站点语言一致。类型契约来自 ../types/config 中的 CommentConfig。
页面层：四个页面各自决定"在哪里挂评论"。文章页传 post（由组件内部派生路径），自定义页传显式 path。
组件层：index.astro 是唯一的决策点——判断总开关、文章级开关、路径是否有效、选择引擎，然后按需渲染 Twikoo.astro 或 Giscus.astro。引擎差异被完全封装在这两个子组件内。
运行时/外部服务层：Twikoo 走"自托管脚本 + IntersectionObserver 懒加载 + twikoo.init() 连接 envId 后端"；Giscus 走官方挂载逻辑连接 GitHub Discussions。

设计意图：把"是否启用评论 / 用哪个引擎 / 这篇文章要不要评论"这类决策集中在 index.astro 一处，把"如何与特定评论服务交互"这类细节下沉到各引擎子组件，新增引擎时只需扩展一个分支和一个子组件（见扩展点）。

核心实现：统一入口组件

index.astro 是整个评论系统的决策中枢，以下是其完整 frontmatter 逻辑：

astro

---
import type { CollectionEntry } from "astro:content";

import { commentConfig } from "@/config";
import { removeFileExtension } from "@/utils/url-utils";

import Giscus from "./Giscus.astro";
import Twikoo from "./Twikoo.astro";

interface Props {
	post?: CollectionEntry<"posts">;
	path?: string;
}

const { post, path: customPath } = Astro.props as Props;

const path = post
	? `/posts/${removeFileExtension(post.id)}`
	: (customPath ?? "");
// const url = `${Astro.site?.href}${path}`;

let commentService = "";
if (commentConfig?.enable) {
	if (commentConfig.system) {
		commentService = commentConfig.system;
	} else if (commentConfig.twikoo) {
		commentService = "twikoo";
	}
}

const commentEnabled = post ? (post.data.comment ?? true) : true;
---

{
	commentConfig?.enable && commentEnabled && path && (
		<div class="card-base p-6 mb-4">
			{commentService === "twikoo" && <Twikoo path={path} />}
			{commentService === "giscus" && <Giscus path={path} />}
			{commentService === "" && null}
		</div>
	)
}

Source: src/components/comment/index.astro

逐段解析这段代码的关键行为：

配置来源：组件从 @/config 桶文件读取 commentConfig，而不是直接 import @/config/commentConfig。这是项目规范——直接引入会绕过 overrides/ 深合并，拿到未覆盖的默认值（见 CONTENT_SEPARATION.md 的明确警告）。
路径派生优先级：传了 post 就用 post.id 去掉扩展名后拼成 /posts/<id>；否则使用调用方传入的 path，两者都没有则为 ""。注意 path 为空字符串时模板条件 path && 为假，整块评论区域不渲染——这天然防御了"既没传 post 也没传 path"的误用。
引擎选择的降级链：system 字段是首选；若未设置但配置了 twikoo 对象，则回退到 twikoo。若两者皆空，commentService 保持 ""，模板渲染 null——即便总开关 enable: true，也会静默不输出，不会抛错。
文章级开关：post.data.comment ?? true 表示 frontmatter 里写 comment: false 才会关闭；不写该字段默认开启。自定义页（无 post）恒为开启。
样式外壳：无论哪个引擎，容器统一使用 card-base p-6 mb-4，保证评论区视觉与站点卡片体系一致。

核心流程

以下是用户访问一篇启用评论的文章时，从 SSG 构建到运行时初始化的完整时序（以 Twikoo 为例）：

Loading diagram...

流程要点（均可对应到源码）：

构建期零评论请求：评论相关 JS 在页面加载时不下载，首屏 LCP 不受评论系统影响。
懒加载触发：setupLazyLoad() 对 #twikoo-container 建立 IntersectionObserver，rootMargin: "200px" 让脚本在用户"即将看到"评论时就开始加载，掩盖网络延迟。
去重保护：twikooLoaded 标志 + document.getElementById("twikoo-script-loaded") 双重检查，防止重复注入脚本标签。
运行时路径校正：初始化时用 getCurrentPath()（去掉尾部 / 的 window.location.pathname）覆盖构建期传入的 path，确保在 Swup 客户端路由下评论串仍能对准当前页面。

Twikoo 引擎实现细节

Twikoo.astro 的 frontmatter 只做一件事——把全局配置与挂载点、路径合并：

astro

---
import { commentConfig } from "@/config";

interface Props {
	path: string;
}

const config = {
	...commentConfig.twikoo,
	el: "#tcomment",
	path: Astro.props.path,
};
---

<div id="twikoo-container" class="twikoo-container">
	<div id="tcomment"></div>
</div>

Source: src/components/comment/Twikoo.astro

关键运行时片段——脚本加载与防重：

async function loadTwikooScript() {
	if (
		twikooLoaded ||
		document.getElementById("twikoo-script-loaded")
	) {
		return;
	}
	return new Promise((resolve, reject) => {
		const script = document.createElement("script");
		script.id = "twikoo-script-loaded";
		script.src = TWIKOO_SCRIPT_URL;
		script.async = true;
		script.onload = () => {
			twikooLoaded = true;
			resolve();
		};
		script.onerror = reject;
		document.head.appendChild(script);
	});
}

async function initTwikoo() {
	const commentEl = document.getElementById("tcomment");
	if (!commentEl) {
		return;
	}

	try {
		await loadTwikooScript();

		if (typeof twikoo === "undefined") {
			console.warn("[Twikoo] 脚本加载失败");
			return;
		}

		commentEl.innerHTML = "";
		const dynamicConfig = createTwikooConfig();
		await twikoo.init(dynamicConfig);
	} catch (error) {
		console.error("[Twikoo] 初始化失败:", error);
	}
}

Source: src/components/comment/Twikoo.astro

这段实现的工程考量：

自托管脚本：TWIKOO_SCRIPT_URL = "/assets/js/twikoo.all.min.js" 使用站点本地资源而非 CDN，避免第三方 CDN 不可用导致评论区失效，也减少一次外部 DNS/TLS。
Promise 化的加载：script.onerror = reject 使网络失败可以被 initTwikoo 的 try/catch 捕获并 console.error，而不是静默挂起。
双保险去重：模块闭包变量 twikooLoaded 防同一页面重复初始化；DOM 里的 twikoo-script-loaded id 防跨脚本实例重复注入 <script>。
初始化前清空：commentEl.innerHTML = "" 清掉可能残留的旧内容（如 Swup 换页后容器复用），避免 Twikoo 渲染叠加。
动态配置：createTwikooConfig() 在初始化瞬间读取 getCurrentPath()，保证 path 与浏览器真实地址一致。

Swup 视图切换兼容（懒加载与钩子注册）：

function setupLazyLoad() {
	const container = document.getElementById(TWIKOO_CONTAINER_ID);
	if (!container) {
		return;
	}

	observer = new IntersectionObserver(
		(entries) => {
			if (entries[0].isIntersecting) {
				observer.disconnect();
				observer = null;
				initTwikoo();
			}
		},
		{ rootMargin: ROOT_MARGIN },
	);

	observer.observe(container);
}

function setupSwupHooks() {
	if (window.swup?.hooks) {
		window.swup.hooks.on("content:replace", () => {
			setTimeout(setupLazyLoad, 200);
		});
	}
}

Source: src/components/comment/Twikoo.astro

content:replace 是 Swup 完成内容替换后的钩子；组件在其回调中延迟 200ms 再重建懒加载观察器，给 DOM 换页留出稳定窗口。
对应的 cleanup() 会在适当时机 observer.disconnect() 并 swup.hooks.off("content:replace", initTwikoo) 解绑，防止内存泄漏与重复初始化（见 Twikoo.astro L86-L94）。

使用示例：页面接入

文章页接入（传 post）

astro

<!-- src/pages/posts/[...slug].astro 片段 -->
<!-- 评论 -->
<Comment post={entry} />

Source: src/pages/posts/[...slug].astro

permalink 路由采用完全相同的用法（<Comment post={entry} />），见 src/pages/[...permalink].astro。

自定义页面接入（传 path）

astro

<!-- src/pages/about.astro 片段 -->
<div class="mt-4">
	<Comment path="/about/" />
</div>

Source: src/pages/about.astro

友链页同样通过 <Comment path="/friends/" /> 挂载评论，见 src/pages/friends.astro。自定义页因不涉及 post.data.comment，评论恒为开启，其评论串以传入的 path 为唯一标识。

配置选项

全部配置集中在 src/config/commentConfig.ts：

import type { CommentConfig } from "../types/config";
import { SITE_LANG } from "./siteConfig";

// 评论系统配置
export const commentConfig: CommentConfig = {
	enable: false, // 启用评论功能。当设置为 false 时，评论组件将不会显示在文章区域。
	system: "twikoo", // 评论系统选择: "twikoo" | "giscus"
	twikoo: {
		envId: "https://twikoo.vercel.app",
		lang: SITE_LANG,
	},
	giscus: {
		repo: "your-github-username/your-repo-name",
		repoId: "your-repo-id",
		category: "Announcements",
		categoryId: "your-category-id",
		mapping: "pathname",
		strict: "0",
		reactionsEnabled: "1",
		emitMetadata: "0",
		inputPosition: "top",
		theme: "preferred_color_scheme",
		lang: SITE_LANG,
		loading: "lazy",
	},
};

Source: src/config/commentConfig.ts

顶层选项

选项	类型	默认值	说明
`enable`	`boolean`	`false`	全局总开关；`false` 时评论组件不出现在文章区域
`system`	`"twikoo" \| "giscus"`	`"twikoo"`	生效的评论引擎；未设置时会回退检查 `twikoo` 对象是否存在

`twikoo` 选项

选项	类型	默认值	说明
`envId`	`string`	`"https://twikoo.vercel.app"`	Twikoo 服务端地址（Vercel/Netlify 云函数或自部署 URL）
`lang`	`string`	`SITE_LANG`	评论界面语言，来自 `siteConfig` 的语言常量

`giscus` 选项

字段与 giscus.app 生成的参数一一对应（均以字符串形式存储）：

选项	默认值	说明
`repo`	`"your-github-username/your-repo-name"`	承载评论的 GitHub 仓库
`repoId`	`"your-repo-id"`	giscus 生成的仓库 ID
`category`	`"Announcements"`	Discussions 分类名
`categoryId`	`"your-category-id"`	分类 ID
`mapping`	`"pathname"`	页面与 Discussion 的映射方式
`strict`	`"0"`	严格匹配模式
`reactionsEnabled`	`"1"`	是否启用表情回应
`emitMetadata`	`"0"`	是否发送页面元数据
`inputPosition`	`"top"`	输入框位置（top/bottom）
`theme`	`"preferred_color_scheme"`	跟随系统配色
`lang`	`SITE_LANG`	界面语言
`loading`	`"lazy"`	giscus 自身的懒加载策略

语言覆盖的已知限制

评论语言不会自动跟随 siteConfig.lang。 src/config/commentConfig.ts 在模块顶层引用 siteConfig.ts 里的语言常量填充 Twikoo / Giscus 的 lang，覆盖 siteConfig.lang 时需要同时提供 overrides/commentConfig.ts 覆盖对应字段。

Source: docs/CONTENT_SEPARATION.md

原因：lang 是在模块求值期被固化为字面值的，后续修改 siteConfig.lang 不会回写 commentConfig.twikoo.lang，因此必须用独立的 override 文件同步覆盖。

API Reference

`Comment`（src/components/comment/index.astro）

统一评论入口组件。

Props：

参数	类型	必填	说明
`post`	`CollectionEntry<"posts">`	可选	文章集合条目；提供后由组件派生 `/posts/<removeFileExtension(post.id)>` 作为评论路径，并读取 `post.data.comment` 作为文章级开关
`path`	`string`	可选	显式评论路径，仅在未传 `post` 时生效（如 `/about/`、`/friends/`）

行为规则：

post 与 path 同时传入时以 post 为准（三目表达式优先级）。
两者都缺省时 path === ""，组件不渲染任何内容。
渲染条件为 commentConfig?.enable && commentEnabled && path 三者同时成立。

内部计算属性：

名称	类型	来源
`path`	`string`	由 `post` 派生或取 `customPath ?? ""`
`commentService`	`string`	`system` 存在取之；否则若存在 `twikoo` 配置则 `"twikoo"`；默认 `""`
`commentEnabled`	`boolean`	`post ? (post.data.comment ?? true) : true`

`Twikoo`（src/components/comment/Twikoo.astro）

Props： path: string（必填）——评论串标识。

内部契约： 组装 { ...commentConfig.twikoo, el: "#tcomment", path } 作为基础配置；实际初始化时会用运行时 getCurrentPath() 再次覆盖 path，并固定 el: "#tcomment"。

模块级常量：

常量	值	用途
`TWIKOO_CONTAINER_ID`	`"twikoo-container"`	IntersectionObserver 观察目标
`TWIKOO_SCRIPT_URL`	`"/assets/js/twikoo.all.min.js"`	自托管脚本地址
`ROOT_MARGIN`	`"200px"`	懒加载提前量

`Giscus`（src/components/comment/Giscus.astro）

Props： path: string（必填）。

由 index.astro 在 commentService === "giscus" 时渲染。其内部实现文件为 src/components/comment/Giscus.astro，本页源码阅读预算内未展开其内联脚本细节；其配置契约即上文 giscus 配置表，且与入口组件的路径传参约定一致（实现细节未在本次源码采集中验证，待补充）。

失败模式、边界情况与并发

以下行为均直接来自源码，是评论系统在生产环境的健壮性来源：

场景	行为	源码依据
评论未启用	整块 `card-base` 容器不渲染，无 DOM、无脚本	`commentConfig?.enable && ...` 条件短路
文章 frontmatter `comment: false`	该文章无评论区，其余文章不受影响	`post.data.comment ?? true`
未传 `post` 且未传 `path`	不渲染，不报错	`path && ""` 为假
`system` 与 `twikoo` 均未配置	`commentService === ""` 渲染 `null`	降级链兜底
脚本网络失败	`script.onerror` 触发 reject，被 catch 后 `console.error("[Twikoo] 初始化失败:", error)`，页面其余功能不受影响	Twikoo.astro L59, L81-L83
脚本加载成功但全局 `twikoo` 未定义	提前 `console.warn("[Twikoo] 脚本加载失败")` 并 return	`typeof twikoo === "undefined"` 检查
评论容器不存在（如被条件渲染裁剪）	`initTwikoo` 直接 return，不抛异常	`if (!commentEl) return`
重复初始化（Swup 换页/脚本重入）	模块标志 + DOM id 双重去重，脚本只注入一次	`twikooLoaded \|\| getElementById("twikoo-script-loaded")`
视图切换	`content:replace` 钩子延迟 200ms 重建观察器；`cleanup()` 断开 observer 并解绑钩子	Twikoo.astro L86-L94, L116-L121

并发与生命周期要点：

observer、twikooLoaded 是内联脚本闭包内的可变状态；observer.disconnect() 后置 null，保证"触发即失效"的一次性语义，用户快速滚动不会重复调用 initTwikoo()。
Swup 是站点的 SPA 化层。评论组件与其集成的关键假设是：换页后 #twikoo-container 是新 DOM，因此必须重新 observe；而 <script> 标签本身可能残留，所以用 DOM id 而非仅闭包变量判断脚本是否已加载。
评论数据一致性完全由外部服务保证：Twikoo 以 path（最终取运行时 pathname）作为评论串键，Giscus 以 mapping: "pathname" 映射 Discussion。因此站点路由变更会影响历史评论关联。

性能与运维要点

首屏零成本：构建产物中评论部分只有静态 HTML 容器和一段小体积内联引导脚本；twikoo.all.min.js（本地自托管）仅在懒加载命中后才请求。
200px 提前量：ROOT_MARGIN = "200px" 是"掩盖加载延迟"与"避免无效加载"的折中——用户滚到评论区前 200px 就开始拉脚本，通常到达时已可交互。
Giscus 侧的懒加载：配置默认 loading: "lazy"，与组件层的懒加载策略形成一致。
运维关注点：Twikoo 后端（envId）的可用性直接决定评论区可用性；脚本自托管在 /assets/js/twikoo.all.min.js，升级 Twikoo 版本需同步替换该文件。Giscus 则依赖 GitHub Discussions 与 giscus.app 服务的可用性。
故障表现：上述所有失败路径都只输出 console.warn/error，评论区区域可能留白但不会破坏页面其余部分，属于显式的降级设计。

扩展点

新增第三方评论引擎的接入面非常小：

在 CommentConfig 类型（src/types/config）中声明新引擎的配置对象。
在 commentConfig.ts 增加默认配置，并把 system 类型扩展为新引擎字面量。
在 src/components/comment/ 下新增 Xxx.astro 子组件，接受统一的 path: string prop，自行处理挂载与运行时初始化。
在 index.astro 的 JSX 分支中增加一行：{commentService === "xxx" && <Xxx path={path} />}。

引擎之间彼此隔离，互不感知；index.astro 的决策逻辑无需理解引擎内部实现，这是该设计的可扩展性来源。若沿用懒加载模式，建议复制 Twikoo 的 IntersectionObserver + 脚本去重 + Swup 钩子 三件套以保证一致的性能与换页行为。

src/components/comment/index.astro — 统一入口与引擎选择
src/components/comment/Twikoo.astro — Twikoo 懒加载实现
src/components/comment/Giscus.astro — Giscus 引擎组件
src/config/commentConfig.ts — 全局评论配置
docs/CONTENT_SEPARATION.md — 配置覆盖机制与评论语言限制
README.md — 评论系统启用说明（各语言 README 均有对应段落）

评论系统

Purpose and Scope

Overview

Architecture

核心实现：统一入口组件

核心流程

Twikoo 引擎实现细节

使用示例：页面接入

文章页接入（传 post）

自定义页面接入（传 path）

配置选项

顶层选项

twikoo 选项

giscus 选项

语言覆盖的已知限制

API Reference

Comment（src/components/comment/index.astro）

Twikoo（src/components/comment/Twikoo.astro）

Giscus（src/components/comment/Giscus.astro）

失败模式、边界情况与并发

性能与运维要点

扩展点

Related Links

Sources

`twikoo` 选项

`giscus` 选项

`Comment`（src/components/comment/index.astro）

`Twikoo`（src/components/comment/Twikoo.astro）

`Giscus`（src/components/comment/Giscus.astro）