CloakBlog v1.9.5：深色模式三态、写作热力图、搜索增强与 Lighthouse CI

这次发的是 v1.9.5。这版没有大改视觉，更多是「把一直想做的小事做掉」+「给站点加几道自动化守门员」。下面按主题过一遍。

TL;DR

深色模式支持 auto / light / dark 三态，终于会跟着系统走了
此刻页新增 GitHub 风格发布热力图，一眼看全年写作节奏
站内搜索支持 结果缩略图 和 tag: / category: 语法筛选
集成 KaTeX，文章里能写行内 $...$ 和块级 $$...$$ 公式了
新增 pnpm new 一键建文、构建时 自动扫断链 / 图路径
接入 Lighthouse CI，每次 push / PR 自动跑性能与无障碍审计
补全 about / archive / gallery / friends / now 的结构化数据，并加固了安全响应头

一、深色模式：终于「懂」系统了

之前深色模式只有「浅色 / 深色」两档，手动切换。问题是：白天切了深色，晚上忘了切；或者系统已经是深色，进站点却是亮的——很割裂。

这次把 ThemeScript 重写成三态：

自动（auto）：跟随系统的 prefers-color-scheme，系统暗它就暗，系统亮它就亮；
浅色 / 深色：保留手动覆盖，优先级高于自动；
Header 的主题按钮新增了「自动」图标，三态之间点一下切换。

为什么要做三态

两态方案要么信用户、要么信系统，总有一头不满意。三态的本质是把「跟随系统」也变成一个显式可选项，而不是默认行为。这样既尊重系统偏好，又给想强控的人留了后路。

实现上要注意首屏闪烁（FOUC）：脚本必须在 <head> 里同步执行，先读 localStorage 的偏好，没有偏好就回落到 prefers-color-scheme。否则刷新瞬间会先白后黑，很晃眼。

二、此刻页：一张「写作热力图」

/now 页面本来是「此刻档案 + 历史时间线 + 一言墙」。这次加了一张 GitHub 风格发布热力图：

53 周 × 7 天的网格，5 级颜色映射（发文越多越深）；
暗色模式单独配色，不会出现亮底上的刺眼深块；
顶部统计「本年发文数」和「最高产的一天」。

对写博客的人来说，这张图挺治愈——哪周偷懒、哪周爆发，一眼可见。它直接从已发布文章的日期聚合，不依赖任何外部服务，纯构建期计算。

三、站内搜索：看得见、筛得准

搜索页这次有两个实在的增强：

结果带 OG 缩略图：每篇结果左边多一张封面图，列表不再是一排排纯文字，扫起来快很多；
tag: / category: 语法筛选：比如输入 tag:Astro 只搜带 Astro 标签的文章，category:技术 限定分类。输入框下方还加了一行语法提示，不用去翻文档。

缩略图用的是构建期生成的 OG 图（就是分享到社交平台那张 1200×630 的图），所以不增加运行时开销。

四、数学公式：KaTeX 上车

有些技术文章（比如讲算法复杂度、概率、线性代数）迟早要写公式。以前只能贴图，既糊又不能选中。

这次在 astro.config.mjs 里挂上 remark-math + rehype-katex：

行内公式用 $E = mc^2$ ；
块级公式用 $$...$$ 独占一行。

渲染交给 KaTeX，离线、快、中文友好。举个块级的例子：

\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}

五、两个「写博客的人自己用得上的小工具」

5.1 `pnpm new`：一键建文

以前开新文章要手抄 frontmatter（title / description / pubDate / category / tags……），容易漏字段。现在 scripts/new-post.mjs 帮你生成带模板的新文件：

pnpm new "我的新文章"

会自动填好日期、留好占位，直接开写。

5.2 构建时自动扫断链

scripts/check-links.mjs 接进了 build 脚本链：构建完成后自动检查内部链接 404 和图片路径失效，扫到问题直接让构建失败。

为什么放在构建期而不是运行时

断链是「悄悄积累」型的 bug——一篇文章改了 slug，三篇引用它的文章就一起 404，自己很难发现。把它变成构建失败，等于每次发布前强制做一次全站体检，问题在部署前就被拦下，而不是等读者踩到。

六、Lighthouse CI：给性能装上「自动守门员」

光靠人记得测性能不现实。这次加了 lighthouserc.json + 一个 GitHub Actions workflow：

对首页、about、archive、search、now、gear、gallery、friends 共 8 个页面跑 desktop preset 审计；
push 到 main 或开 PR 时自动运行；
结果输出到 PR 的 Step Summary 表格（Performance / Accessibility / Best Practices / SEO 四分项）。

阈值设的是：性能、最佳实践 ≥ 0.9（warn），无障碍、SEO ≥ 0.9（error，不达标直接拦）。以后每次改动，性能有没有退步，数字说话。

七、结构化数据 & 安全加固

SEO 这块补了几处缺失的 JSON-LD：

about 页 → ProfilePage
archive / gallery / friends → CollectionPage / ImageGallery
now 页 → WebPage

搜索引擎能更准地理解页面类型，对收录和富结果有帮助。

安全响应头也加了两道：public/_headers 里补上 Strict-Transport-Security（HSTS，带 preload）和 X-DNS-Prefetch-Control；同时把锁文件统一成 pnpm-lock.yaml，避免 npm / pnpm 混用带来的不确定性。

小结

v1.9.5 不算「大版本」，但它把几件「一直想做、做了就省心」的事一次做完了：模式跟随系统、写作节奏可视化、搜索更好用、公式能写、建文和体检自动化、性能有 CI 守着。后续如果哪块用着不顺手，欢迎在评论区拍砖。