一、原作者想解决什么#

把博客原有的评论系统从 Giscus 迁到自建留言板，动机很直接：

• 更轻量：访客无需 GitHub 登录就能留言；
• 深度集成：能塞进 Astro 主题的视觉语言里；
• 自己掌控数据：可随意定制样式、未来加邮件通知或后台管理；
• 技术载体选了 Vercel KV（Redis）。

二、技术栈一览#

三、数据模型与接口#

扁平数组 + slug 区分页面：每条留言是一段对象，靠 slug 字段（默认取 location.pathname）过滤属于哪篇文章；嵌套回复用 parentId 指向父留言。

1
interface Message {
2
  id: string;
3
  slug?: string;
4
  parentId?: string;
5
  nickname: string;
6
  content: string;
7
  email?: string;
8
  website?: string;
9
  avatar: string;
10
  createdAt: number;
11
  replies?: Message[];   // 前端建树时填充
12
  os?: string; browser?: string; device?: string;
13
}

接口只有两个：

• GET /api/messages/?slug=xxx —— 取该页留言，返回 JSON；
• POST /api/messages/ —— 收 nickname / content / email / website / parentId / slug，后端用 ua-parser-js 解析 User-Agent 入库设备信息，并按邮箱决定头像。

头像逻辑：邮箱匹配 QQ 号（或 @qq.com）→ 用 https://q1.qlogo.cn/g?b=qq&nk=<qq>&s=100；否则用 dicebear 生成 identicon：

1
const qqMatch = email.match(/^(\d{5,11})(@qq\.com)?$/);
2
const avatar = qqMatch
3
  ? `https://q1.qlogo.cn/g?b=qq&nk=${qqMatch[1]}&s=100`
4
  : `https://api.dicebear.com/7.x/identicon/svg?seed=${nickname}`;

四、防滥用与嵌套回复#

反垃圾只做了三件事：非空校验（后端 400、前端按钮 disabled）、长度上限（昵称 20 / 内容 500 / 邮箱 50 / 网址 100）、以及总量硬砍 2000 条（messages.pop() 踢最旧）。原文没有验证码，也没有频率限制。

嵌套回复：库里扁平存，前端用 Map<id> 建树——遍历时若 parentId 存在就塞进父级的 replies，否则当根留言；根留言按 createdAt 倒序（新在前），回复按正序（对话时间线）。渲染用 <svelte:self> 组件自调用实现无限层级缩进。

五、实时性与几个取舍#

• 非实时推送：没有 WebSocket / SSE，提交成功后 fetchMessages() 重新拉全量刷新列表；
• 延迟拉取防 LCP 阻塞：onMount 里 setTimeout(() => fetchMessages(), 100)，避免阻塞首屏；
• Markdown 解析器单例化：若在每条留言的 MessageItem.svelte 里 new MarkdownIt() 会每条建实例、吃内存，于是用 Svelte 的 <script context="module"> 把解析器提升为模块级单例；
• 本地降级：无 Redis 环境变量时自动改用 data/messages.json（fs.writeFileSync），降低本地起环境的门槛；
• 存储简化：用单 Key 数组而非 Redis 复杂结构（Sorted Set / Hash），以简化逻辑，再用 2000 条上限防止无限膨胀。

XSS 防护是把 markdown-it 渲染结果过 sanitize-html 白名单（span 仅放行 spoiler class），并支持 ||黑幕|| 转 <span class="spoiler"> 的剧透语法：

1
<script context="module" lang="ts">
2
  import MarkdownIt from "markdown-it";
3
  import sanitizeHtml from "sanitize-html";
4
  const md = new MarkdownIt({ html: true, breaks: true, linkify: true });
5
  const sanitizeOptions = {
6
    allowedTags: ["p","b","i","em","strong","a","code","pre","span","img","details","summary"],
7
    allowedAttributes: { img: ["src","alt","title"], a: ["href","title","target"], span: ["class"] },
8
    allowedClasses: { span: ["spoiler"] },
9
  };
10
  function renderContent(text: string) {
11
    const withSpoilers = text.replace(/\|\|(.*?)\|\|/g, '<span class="spoiler">$1</span>');
12
    return sanitizeHtml(md.render(withSpoilers), sanitizeOptions);
13
  }
14
</script>

六、与「留心博客」自建评论的对比#

笔者的方案 2026-09-12 上线，后端是独立 workers/comments Worker + D1，前端 Comments.astro。同一道题，两个答案：

逐项说笔者的判断：

1. 存储架构：本站更”正”。 原文把所有留言塞进一个 Redis Key 的数组，每次读写都要全量序列化；作者自己用 2000 条 pop() 兜底。文章一多、某篇爆火，全量读写会越拖越慢，且无法按 slug 在服务端分页。本站用 D1 可以直接 WHERE post_slug = ? ORDER BY ... LIMIT，天然索引、可分页、还能用递归 CTE 做级联删除——长期更稳。
2. 后端解耦：本站更干净。 原文把 src/pages/api/messages.ts 声明 prerender=false 混进 Astro 静态站，靠 Vercel 把这条路由变 Serverless；本站把评论彻底拆成独立 Worker，Astro 只 fetch，不污染构建、不受静态输出约束。
3. 大陆可达性：本站已修坑，原文未讨论。 原文的 blog.shiro.team 看着是 Cloudflare 代理域名，但教程本身没提部署地域。本站刚踩过”*.workers.dev 在国内被 DNS 污染连不上”的坑，已绑自定义域名——这一条本站更稳。
4. 防垃圾：本站更严。 原文那版没有频率限制 / 验证码，匿名留言板一旦被爬被刷就是裸奔；本站已有蜜罐 + 限流 + 可选审核。
5. XSS 取舍：各有权衡。 原文支持富文本（||黑幕||、链接、代码块），但要背一条 sanitize 管线；本站走纯文本，牺牲富文本换”结构上不可能 XSS”。不是谁错，是取舍不同。

七、值得借鉴的点（按性价比）#

八、小结#

这篇教程对笔者的价值，主要在验证路线而非提供新方案：在存储（D1）、后端解耦（独立 Worker）、反垃圾（限流+蜜罐）、大陆可达（自定义域名）四个关键点上，本站 2026-09-12 的那版都优于或等于它。唯一明显不如、且成本低值得补的，是用户输入缓存和拉取延迟优化——两项几乎零风险。

如果你的博客也在用 Giscus 或别的第三方评论，不一定要马上换；但有两件事值得现在确认：评论数据存在哪里、出问题能不能拿回来，以及访客为了留一句话要付出多少成本。这两点，正是我们各自”出走 Giscus”的共同起点。

相关阅读#

• 自建评论系统：从 Giscus 到 Cloudflare Workers + D1：本站评论后端的完整实现与踩坑记录。
• 右侧悬浮工具栏：回顶部、随机一篇、目录抽屉与评论跳转：右下角”跳评论”按钮，直达的就是这套自建评论区。