peroe 的博客

27 篇文章的站内搜索：81 KB 索引与一次 304

Sat, 24 Oct 2026 15:40:00 GMT

静态站没有后端，所以站内搜索必须想在前面：索引在构建期生成，匹配在浏览器里做。

这个博客的方案很朴素：一个 search.json + 前端子串匹配。27 篇文章跑下来够用，但拆开量一遍才发现，里面藏着一个"每次搜索都重新下载索引"的问题。

方案长什么样

构建期把每篇文章的标题、描述、正文和链接写成一个大 JSON：

[
  { "title": "…", "description": "…", "content": "…", "link": "/posts/…", "published": "…" }
]

前端打开搜索面板时 fetch("/search.json")，然后在内存里对每个字段做 indexOf：

for (const post of posts) {
  for (const field of [post.title, post.description, post.content]) {
    const index = fieldLower.indexOf(keywordLower);
    if (index !== -1) { /* 截取命中位置前后 40 字的摘要 */ }
  }
}

实测（本地 Chrome，首访）：

指标	值
索引体积	193 KB（UTF-8）/ 81 KB（字符数）
条目	26 篇（加密文章不进索引）
首次 fetch	422 ms（含下载）
再次 fetch（默认缓存）	226 ms

修掉的那个问题：`no-store`

打开搜索面板的代码原本是：

await fetch("/search.json", { cache: "no-store" });

no-store 的意思是永远不要用缓存——于是每次打开搜索都重新下载 81 KB。对桌面宽带无所谓，对移动网络就是每次多几十 KB。

服务端给这个文件的是 cache-control: public, max-age=0, must-revalidate + ETag，也就是允许缓存但每次要验证。所以只要别写 no-store，浏览器就会带 If-None-Match 走条件请求：

GET /search.json
If-None-Match: W/"39bf20e5ce2f5db47093048c0770cc81"
→ HTTP 304 Not Modified（几百字节）

改成 cache: "default" 之后，第二次以后的搜索只花一次往返，不再传那 81 KB。

踩坑提示：force-cache 在这里不能用——索引文件名没有内容哈希，强缓存会读到发文章之前的旧索引。default + 服务端 ETag 才是正确组合。

这套方案的天花板

1. 线性扫描的代价随篇数增长。

26 篇时遍历 26 次，用户感觉不到。但索引是全量下载的——200 篇时大概 600 KB，每次搜索（哪怕只是第一次）都要传完才能搜。

2. 中文没有分词，只有子串匹配。

「性能优化」→ 能命中（四个字连写）
「性能」「优化」→ 也能命中（子串）
「性能优化」（中间带空格）→ 命中不到

这不算 bug，但要知道它的边界：这套搜索本质是「整段文本包含关键词」，不是「按词检索」。

什么时候该换：文章超过 100 篇，或者需要词权重、高亮、拼音搜索。那时候该上 Pagefind（构建期生成倒排索引 + 分片加载）或 MiniSearch（前端建倒排索引）。现在 27 篇、81 KB、首搜 422 ms，不值得换。

一个取舍：索引里要不要放全文

现在 content 字段放了正文，所以：

好处：能搜到正文里的细节（比如某篇文章里提到的 cache-control）；
代价：索引随文章数线性变胖。

折中方案是只索引标题 + 描述 + 前 N 字。但那样会丢掉「搜正文」的能力，而技术博客里最常搜的恰恰是术语——所以我保留了全文，把「索引会不会太大」留给篇数增长时再决定。

小结

站内搜索不是"接个库"就完事，三个决定要先想清楚：

索引在哪生成：静态站只能在构建期（浏览器里建索引太慢）；
怎么匹配：子串匹配足够简单，但要知道它不懂分词；
怎么缓存：索引是大文件，no-store 会让每次搜索都重下——用 default + ETag 走 304。

三条都记下来之后，这套 60 行的方案就能一直用到文章上百篇。

顺带一提，这套「构建期生成索引、浏览器里匹配」的思路，和构建产物与访客成本里讲的按需加载是同一个道理：能不进关键路径的，就别进。

构建产物 16 MB，访客每次只下 28 KB

Sat, 24 Oct 2026 15:20:00 GMT

跑完性能体检后我一直有两套数字，但从来没把它们放在一起看：

部署体积：dist 目录 16.04 MB、313 个文件；
访客成本：首页实际传输 27.9 KB（brotli 压缩后）。

差 570 倍。这篇就把这个差距拆开——哪些体积是真的，哪些是错觉。

dist 里到底装了什么

类型	文件数	体积	占比
HTML	57	5.95 MB	37.1%
WebP 配图	91	4.91 MB	30.6%
JS	88	3.31 MB	20.6%
字体	59	1.02 MB	6.4%
XML（sitemap / rss）	4	0.37 MB	2.3%
JSON / CSS / SVG	8	0.47 MB	4.7%

最扎眼的是 JS 那 88 个文件、3.31 MB。而最大的六个文件里有四个是图表引擎：

585.3 KB  _astro/mermaid.core.js
481.0 KB  _astro/wardley.js
431.4 KB  _astro/cytoscape.esm.js
253.4 KB  _astro/katex.js

Mermaid 全家桶 1.6 MB。 而这个站目前一张 Mermaid 图表都没有。

但访客从没下载过这 1.6 MB

因为它是动态 import 的：

let mermaidLoader: Promise<any> | null = null;
const loadMermaid = async () => {
  if (!mermaidLoader) {
    mermaidLoader = import("mermaid").then((mod) => mod.default);
  }
  return mermaidLoader;
};

只有当页面里真的出现 ```mermaid 代码块时才会调用它。于是这 1.6 MB 变成了永远不会被请求的部署体积——它在 dist/ 里占位，但不进任何人的关键路径。

实测传输量：

页面	传输（brotli）
首页 `/`	27.9 KB
文章页 `/posts/blog-view-counter/`	47.5 KB

三个让差距变大的机制

1. 压缩：130 KB → 28 KB。 HTML 平均每页 104 KB（未压缩），Cloudflare 默认开 brotli，压到 25~30 KB。这是最容易忽略的一半——看 dist 的体积永远会高估 4~5 倍。

2. 按需加载：1.6 MB 永不下载。 除了 Mermaid，KaTeX（数学公式）也是同一个模式。这类"可能用得上"的依赖放动态 import，代价从「每个访客」变成「零」。

3. 长缓存：第二次访问不再请求。 构建产物文件名带内容哈希，/_astro/ 下全部是：

cache-control: public, max-age=31536000, immutable

（这条是三层缓存那篇改的，之前所有资源都是 max-age=0。）

三个机制叠起来，才有了「16 MB 部署、28 KB 首访、几乎零次访」。

顺手修掉的一个小浪费

拆 HTML 时发现每页 40 KB 是内联脚本（44 个 <script>），其中最大的那块里塞着我写的解释性注释——is:inline 的脚本会被原样输出，注释也算字节。

改法是把长注释搬到文档、脚本里只留一行结论：

	改前	改后
首页 HTML	134 KB	132.9 KB
内联脚本合计	40.0 KB	39.5 KB

省下 509 字节/页。数字很小，但它说明一件事：is:inline 的脚本要当成"发给用户的源码"来写，注释不是免费的。

（真正的大头在别处：40 KB 内联脚本里，最大的一块 6 KB 是 Cookie 横幅的引导代码——这也是它成为 LCP 元素的原因之一，见和横幅抢 LCP。）

该看哪个数字

我的结论是：看三个，而不是一个。

数字	看什么	什么时候看
部署体积	部署限制（Cloudflare 单 Worker 2 万文件 / 单文件 25 MiB）	加依赖时
首访传输	真实的首屏成本	优化性能时
二次访问	缓存是否生效	改缓存策略时

只看第一个会去删没用的依赖（比如把 Mermaid 删了），但收益是 0——因为它本来就没被下载。只看第二个会忽略部署限制。三者一起看，才知道该动哪里。

小结

部署体积 ≠ 访客成本，中间有压缩、按需加载、缓存三道闸；
动态 import 的依赖要算「永远不下载」，不要为了 dist 好看去删它；
内联脚本属于源码分发，注释也算字节；
判断优化优先级时，先量一次「首页压缩后到底多少 KB」——那才是用户付出的代价。

可访问性体检：三个真问题与三次假警报

Sat, 24 Oct 2026 15:00:00 GMT

SEO 体检做久了会形成一个偏见：只关心搜索引擎看不看得懂。但同一批标记，屏幕阅读器和键盘用户也在用——比如 h1 结构、图片 alt、表单的无障碍名称。

这轮我给博客做了一次可访问性体检，查出三个真问题，也踩到三次「体检脚本自己骗人」。

六项检查，跑一遍就知道

检查	判据
`lang`	`<html lang>` 存在且正确
重复 id	同一页面内 `id` 不重复（重复 id 是非法 HTML，锚点与 `aria-labelledby` 都会失准）
图片 alt	没有缺 `alt` 的 `<img>`
无障碍名称	每个可聚焦元素都要有可见文本 / `aria-label` / `title`
对比度	文字与背景的对比度 ≥ 4.5:1（大字 ≥ 3:1）
减少动效	CSS 里有 `prefers-reduced-motion` 分支

实现都是十几行 DOM 查询，不需要装任何依赖。

三个真问题

1. 每个页面都有两个 id="sidebar"。

外层网格容器（MainGridLayout）和侧栏组件内部（SideBar）用了同一个 id。重复 id 不会报错、页面也照常显示，但：

锚点跳转（#sidebar）只会跳到第一个；
aria-labelledby 指向它时，读屏可能读到错的那个。

修法是把内层改成 id="sidebar-inner"——改之前先确认没有任何 CSS/JS 依赖 #sidebar（我扫了一遍，确实没有）。

2. 三个搜索框都没有无障碍名称。

它们只有 placeholder="搜索"。而 placeholder 有两个问题：输入内容后会消失，而且它不保证被当作可访问名称。读屏用户 Tab 到输入框时，听到的是一个没有标签的文本框。

修法是补 aria-label="搜索文章"——三个 input（桌面版、移动版、搜索面板内）都要补。

3. 键盘焦点环在深色背景上几乎看不见。

这条最隐蔽，因为我第一版体检把它判成了「通过」：outline: auto 1px —— 轮廓确实存在。但截图一看：

第二个 Tab 焦点: 归档 | outline: auto 1px rgb(16, 16, 16)

rgb(16,16,16) 是近黑色，压在本站 #0f1219 的深色背景上，等于没有。

修法是统一焦点样式，只在键盘导航时出现：

:where(a, button, input, select, textarea, summary, [tabindex]):focus-visible {
    outline: 2px solid var(--primary);
    outline-offset: 2px;
    border-radius: 4px;
}

改完再量，轮廓变成 solid 2px oklch(0.7 0.15 255)——主题蓝色，Tab 走一遍能清楚地看到光标在哪。

三次假警报（比真问题更值得记）

① 性能脚本报 LCP 1.9 秒。 真因是启动参数里带了 --host-resolver-rules=MAP * ~NOTFOUND（当初为了绕开本机代理），把所有第三方域名都解析成不存在——测出来的是「没有第三方的平行世界」。真实现场是 12 秒。

② SEO 脚本报 10 条「canonical 指向别处」。 真因是中文标签页的 canonical 是 percent-encoded 形式，两者等价，但脚本逐字符比较。改成比较前 unquote() 两边。

③ a11y 脚本报对比度 ratio 1.12（几乎全白 on 全白）。 真因是脚本没把文字颜色的 alpha 与背景合成：text-50 这类半透明文字、sr-only 这类收成 1px 的视觉隐藏元素全被算进了分母。

为什么假警报比漏报更危险：漏报只是没发现问题；假警报会让人去改本来没问题的东西——我差点为了「对比度不达标」去调深色主题的文字色，实际那两处一处是视觉隐藏的 h1、一处是半透明计数。

所以写体检脚本时，我给自己定了两条规矩：

每条判据都要能解释：「为什么这个元素不达标」要能打印出具体值（颜色、比例、坐标），而不是只给一个结论；
先怀疑脚本，再改代码：同一个「问题」出现在全站每个页面时，八成是判据写错了，而不是模板全错。

现在的基线

lang            zh-CN
重复 id         0
图片缺 alt      0
无障碍名称      全部有（3 个搜索框已补 aria-label）
对比度          0 处不达标（大字 ≥3:1、正文 ≥4.5:1）
键盘焦点        主题色 2px 描边，Tab 全程可见
减少动效        prefers-reduced-motion 已支持

小结

可访问性体检的收益不只是「对残障用户友好」：

重复 id / 缺 alt / 无名称的按钮，对爬虫也是语义噪声；
可见焦点环让键盘用户能用——而这个站自己就是写技术的，读者里有一半会按 Tab；
更重要的是，它逼我把「我以为通过了」变成「量出来的结果」。

三行命令就能跑一遍，我把它和 SEO 体检放在同一个目录里，发文章前一起跑。

体检的具体判据与九类历史问题整理在站内 SEO 体检清单里，两套体检可以一起跑。

24 篇文章的站内 SEO：一套可复跑的体检清单

Sat, 24 Oct 2026 14:40:00 GMT

站内 SEO 的问题大多不需要登录任何后台就能发现：构建产物里的 HTML 就是事实。标题多长、描述是不是重复、h1 有几个、canonical 指向哪、结构化数据能不能解析——全都在 dist/ 里。

我给这个博客写了个体检脚本，24 轮下来跑了上百次。这篇把检查项、真实问题与修法整理成一份可以照抄的清单。

八项检查，扫的就是产物

检查	判据
title	12~48 字（含站点后缀），且非空
description	60~160 字，每页唯一
canonical	存在、绝对地址、指向自身（中文路径要按语义比，下面会讲）
h1	恰好 1 个，且非空
`og:image`	存在（分享卡片靠它）
结构化数据	能被 `JSON.parse` 解析
正文厚度	少于 300 字标「偏薄」
内链	统计站内出链数，配合另一个脚本算入链与孤岛

实现只有一百多行：用 glob 遍历 dist/**/*.html，正则取 <head> 里的标签，用一个小型 HTML 解析器数 h1/h2/<img>，再对 JSON-LD 做一次 JSON.parse。

关键前提：先删 dist/。Astro 构建不会清理上一次的产物，我因此扫到过一个线上早已 404 的幽灵页面（/t/），还据此下了一堆错误结论。

九类真实问题（按影响排序）

问题	规模	修法
全站 h1 数量 = 0	28 个页面	布局加 `heading` 属性渲染 `<h1 class="sr-only">`；文章页的 `div#post-title` 改成 `h1`
28 个页面缺 `og:image`	全部列表页	生成 `/og-default.png` 兜底，布局里统一输出 `og:image` + `width/height`
描述重复或过短	十几个页面	每页独立描述；最薄的两个工具页从 292 字补到 1950 字
sitemap 的 XSD 顺序错	2 条 sitemap	必须 `loc → lastmod → changefreq → priority`，否则 Google 报「无法读取此站点地图」
404 页输出两个 `<head>`	1 页	不要再把 `MainGridLayout` 嵌进 `Layout`
RSS 里置顶文排第一	全站 feed	改成按 `published` 倒序（列表页仍保持置顶优先）
内链太稀、孤岛多	12 篇零入链	手工补上下文链接 + 「相关文章」自动生成 + 标签聚合页
11 个标签页缺失	20 个标签	只给 ≥2 篇文章的标签建页（单篇标签是薄内容）
LCP 元素是 Cookie 横幅	全站	提前加载 + 压缩体积（12.1s → 7.4s，未完）

前两项最典型：问题不在某篇文章，而在模板。h1 = 0 意味着所有页面的标题层级都是坏的，搜索引擎只能自己猜哪个是主题。

现在的基线

扫描页面    54 个（24 篇文章 + 11 个标签页 + 静态页 + 分页）
可收录     43 条（sitemap）
体检问题   0 项（只有 /2/ /3/ /404 缺 JSON-LD —— 分页与错误页本来就不需要）
内链       41 条手工 + 67 条自动相关文章

三条「体检本身也会骗你」的教训

1. 脚本的隐含条件要写下来。

我的性能脚本带了一行 --host-resolver-rules=MAP * ~NOTFOUND（当初为了绕开本机代理），副作用是把所有第三方域名都解析失败——于是长期报出「LCP 1.9 秒」，而真实现场是 12 秒。任何"隐含条件"都要在脚本头部写清楚，否则半年后的你会被自己骗。

2. URL 要按语义比，不能按字符比。

中文标签页 /tags/统计/ 的 canonical 是 percent-encoded 形式，逐字符比较会报 10 条假问题。比较前 unquote() 两边。

3. 同一套规则要在多处保持一致。

标签页的建页条件是「≥2 篇文章」，这个条件同时出现在三处：getStaticPaths（决定生成哪些页）、PostMeta（决定哪些标签可点）、sitemap（决定收录哪些 URL）。任何一处漏掉，结果不是 404 就是孤儿页。

怎么复跑

rm -rf dist && pnpm astro build --force     # 干净构建
python seo-audit.py                        # 八项检查
python link-audit.py                       # 入链/出链/孤岛

两个脚本都在我的本地工具目录里、不进仓库——它们不含任何站点私有信息，但也没必要让仓库多两个 Python 文件。

小结

站内 SEO 没什么神秘：把「什么样的页面算合格」写成可执行的判断，然后每次都跑一遍。

真正花时间的是修——尤其是那些"问题在模板里、影响全部页面"的项。但正因为它们在模板里，修一次就永久生效：h1、og:image、canonical 这三件事修完之后，后面每发一篇文章都自动合规。

体检之后更麻烦的是性能：LCP 元素居然是 Cookie 横幅，两次尝试的过程写在和 Cookie 横幅抢 LCP里。

体检不止有 SEO 一种：键盘焦点、对比度、无障碍名称也值得查一遍，过程见可访问性体检。

静态站的标签体系：挖出 11 个可收录页面

Sat, 24 Oct 2026 14:20:00 GMT

做体检时随手查了一下「标签页在不在」，结果发现两件事：没有标签页，而且文章页上也看不到标签。

后者更意外：文章页明明写了 <PostMetadata tags={entry.data.tags} />，但那个组件里根本没有 tags 字段——传进去的参数被静默忽略了。于是 20 个标签只活在 frontmatter 里，对读者和搜索引擎都不存在。

先数一遍：哪些标签值得建页

建站 18 篇 · Astro 11 篇 · 性能 8 篇 · 安全 6 篇
运维 3 篇 · Cloudflare 3 篇 · 统计 2 篇 · 观测 2 篇 · 工程实践 2 篇 · 隐私 2 篇
以下各 1 篇：缓存 / 图片 / SEO / 搜索 / 公告 / HTTPS / 网络 / 排障 / 测量 / 成本

规则很简单：只给 ≥2 篇文章的标签建落地页。

单篇标签的聚合页只有一篇文章 + 一句导语，是标准的薄内容——Google 对这类页面没有好感，而它又会让站内多出 10 个"看起来像页面但没内容"的 URL。所以单篇标签只显示在文章底部（纯文本，不带链接），不建页、不进 sitemap。

最终：10 个标签页 + 1 个索引页 = 11 个新页面，可收录页面从 30 个涨到 41 个（+37%）。

每个标签页长什么样

以 /tags/Astro/ 为例，一个页面要有四样东西：

独立的 title / description（不能复用文章页的，也不能所有标签页共用一句）；
单 h1 —— 由布局的 heading 属性渲染成 <h1 class="sr-only">，可见标题用 h2；
结构化数据 —— CollectionPage + ItemList，把该标签下的文章作为 itemListElement；
内容本身 —— 按时间倒序的文章列表 + 页脚「其他标签」交叉链接。

结构化数据那段值得单独说：标签页的价值是"聚合"，所以用 CollectionPage，而不是 BlogPosting。ItemList 里最多放 20 条，标题直接取文章标题、URL 取绝对地址。

描述怎么生成：唯一、且够长

第一版我自动生成的是：

peroe 的博客中带有「统计」标签的 2 篇文章，按发布时间从新到旧排列。

体检立刻报「description 38 字（建议 60~160）」。而且 10 个标签页都是同一个句式，只有标签名不同——这是重复内容。

改成用该标签下最新两篇文章的标题拼摘要：

peroe 的博客中带有「Astro」标签的 11 篇文章…… 例如：《Astro 静态站的三个隐形约定：CSS 是全局的》、
《静态站的标签体系：挖出 11 个可收录页面》。每篇都附带实测数据与可复现的命令。

结果是每页 100~130 字、彼此唯一，而且自然带上了文章关键词。这也是我后来给「相关文章」组件定描述时用的同一个思路：让自动生成的文案里带真实内容片段。

三个坑

坑一：getStaticPaths 里不能提前编码。

// ❌ 构建直接失败：NoMatchingStaticPathFound: /tags/建站/
params: { tag: encodeURIComponent(tag) }
// ✅ 给原始标签名，Astro 会解码 URL 后再匹配
params: { tag }

这是中文标签必踩的一脚：链接里需要 encodeURIComponent（浏览器行为），但路由参数不能。

坑二：审计脚本对中文路径的 canonical 误报。

/tags/统计/ 的 canonical 是 https://blog.peroe.cn/tags/%E7%BB%9F%E8%AE%A1/ —— 两者等价，但我自己的体检脚本是逐字符比较，于是报了 10 条「canonical 指向别处」。改成比较前先 unquote() 两边，误报清零。

写体检脚本的人容易犯这个错：URL 比较必须按语义比，不能按字符串比。

坑三：sitemap 是手写清单。

新页面建好了但 sitemap 里没有——它不会自己出现。我维护的是一份 staticPages 清单，得手动补 /tags/，再按「≥2 篇」的同一条件生成 10 条标签页条目（lastmod 取该标签下最新文章的更新时间）。建页条件必须和 getStaticPaths 完全一致，否则 sitemap 里会混进 404。

顺带修的一件事：文章页显示标签

标签页有了，但读者是从文章页过来的——所以给 PostMeta 加了标签渲染：

{tags.map((tag) =>
  linkableTags.includes(tag)
    ? <a href={`/tags/${encodeURIComponent(tag)}/`}>{tag}</a>   // ≥2 篇：可点
    : <span>{tag}</span>                                        // 单篇：纯文本
)}

linkableTags 在构建期算好（复用同一份统计），这样单篇标签不会产生 404。

小结

标签体系的价值有两层：

对读者：从一篇文章跳到同主题的其他文章；
对搜索引擎：多出 11 个主题聚合页，能吃「Astro 建站」「网站性能优化」这类单篇标题命中不了的词。

判断标准可以总结成三条：

≥2 篇才建页（薄内容不建）；
描述必须唯一且够长（拼真实标题，别套模板）；
建页条件在 getStaticPaths、sitemap、链接渲染三处保持一致（否则不是 404 就是孤儿页）。

标签页与站点地图的联动细节，见博客 SEO 自我体检那一篇里的体检清单。

和 Cookie 横幅抢 LCP：我试到哪一步就停了

Sat, 24 Oct 2026 14:00:00 GMT

上一篇《我的性能测试骗了我》结尾留了个问题：Lighthouse 表示 LCP 元素是 Cookie 横幅的文案，LCP 12.1 秒。

这一轮我把它当成真正的对手，试了三招，最后停在离目标还有一段距离的地方。过程比结果有用。

三招，逐招看效果

尝试	做法	性能分	FCP	LCP	TBT
改前	横幅等 `window.load` 再加载	37	3.5s	12.1s	1850ms
①	提前到 `DOMContentLoaded`	49	1.6s	7.2s	1480ms
②	① + 横幅体积 −75%	48	1.6s	7.8s	1650ms
③	② + `preload` 横幅脚本	50	1.5s	7.4s	1390ms

① 有效：横幅从 12 秒提前到 7 秒出现，LCP 跟着降了 5 秒。

② 几乎没用：我把横幅从 360×490 压到 320×137（面积 −75%，用官方文档给的 CSS 类名做的），LCP 一点没动 —— 甚至因为测量噪声略涨。

③ 在噪声范围内：preload 让 66 KB 的脚本更早开始下载，但对 LCP 的影响看不出。

为什么「压小」没用

这是这轮最值得记下来的一课：

LCP 判的不是「最大」，而是「最晚出现的那块大字」。

我第一次读到这句话时以为它只是概括，真正踩过才发现它是判据。横幅压小之后，它的文本块确实不再是页面上面积最大的元素了 —— 但它仍然是最后出现的大块，于是 LCP 元素一直是它（Lighthouse 三次都报同一个 p.cc-nb-text）。

换句话说：只要横幅在 7 秒出现、且它的面积还超过页面上其它任何一个内容块，LCP 就是 7 秒。压缩体积只有在「压到比正文还小」且「正文出现得更早」时才可能改变结论 —— 而我实测压到 43.7k px² 时，Lighthouse 依然选了它。

还有一个隐性原因：那是第三方脚本

横幅不是我写的，是 66 KB 的第三方库，在 1.6 Mbps + 4 倍 CPU 下：

下载 66KB（~0.4s）+ 解析执行（~1s，4x 降速）+ 构建 DOM + 渲染那块文本 ≈ 7 秒

我能控制的只有「什么时候开始下载」和「下载完之后长什么样」，控制不了它自身的解析成本。

所以我停在这里

把 LCP 压到 2.5 秒以内，只剩两条路：

A. 换掉这个第三方横幅，自建一个约 2 KB 的同意条。 代价是要自己实现条款文案、偏好中心、以及与 GA4 / Clarity 的联动 —— 这些属于合规实现，不是纯技术活。我停在这里，等站长确认。

B. 接受约 7.4 秒，把优化重心移回内容侧。 从"用户能不能尽快看到内容"的角度，FCP 1.5 秒其实已经不错了；LCP 被横幅绑架是结构性问题。

这轮的实际收益

指标	改前	现在	变化
FCP	3.5s	1.5s	−2.0s
TBT	1850ms	1390ms	−460ms
性能分	37	50	+13
横幅面积	176k px²	43.7k px²	−75%
LCP	12.1s	7.4s	−4.7s（未达 2.5s）

顺手还修了两件小事的：

RSS 排序：之前沿用列表排序（置顶优先），「关于本站」永远是 feed 第一条，新文章反而沉到后面 —— 订阅者看到的"最新"是两个月前的置顶文。改成按时间倒序。
弱锚文本：一条内链的锚是「这篇」，改成「首屏从 392KB 砍到 59KB」。

小结

三招里只有「提前加载」真正有效，而它之所以有效，是因为把大块出现的时间往前挪了 5 秒。压缩体积、preload 都是在优化"这块东西本身"，但 LCP 关心的是"它什么时候出现"。

这也解释了为什么很多站点优化了半天图片和字体，LCP 纹丝不动 —— 先去 Lighthouse 里看 LCP 元素是谁，再决定动哪里。

我的性能测试骗了我：把第三方全拦掉再测

Sat, 24 Oct 2026 13:40:00 GMT

[!WARNING] 这篇是我自己的「打脸记录」：前面几篇性能文章里的数字，是在一个没有第三方脚本的平行世界里测出来的。真实场景要慢得多。

起因

为了写上一篇的对比，我跑了一次 Lighthouse：

Lighthouse 12.8 (mobile)
  得分: 47     FCP 5.5s     LCP 12.4s     TBT 490ms

可我自己的脚本一直在报 LCP 1.9 秒。差 6 倍，必须查清楚。

三个"测量"，三个世界

数据源	FCP	LCP	TBT	请求 / 传输
我的 CDP 脚本	1.4s	1.9s	117ms	41 / 59KB
Lighthouse simulate	5.5s	12.4s	490ms	83 / 1039KB
Lighthouse devtools	3.5s	12.1s	1850ms	83 / 1039KB

请求数差一倍、传输差 17 倍。答案藏在我脚本的启动参数里：

args: ["--no-proxy-server",
       "--host-resolver-rules=MAP * ~NOTFOUND , EXCLUDE blog.peroe.cn , EXCLUDE q2.qlogo.cn"]

这两行本来是为了绕开本机代理（用 CDP 限速时，代理会让连接超时）。副作用是：所有不在白名单里的域名都被解析成 NOTFOUND —— GA4、Clarity、Cookie 横幅、Umami、Giscus 全军覆没。

说白了，我这个脚本测的是「如果这个站没有第三方脚本，它有多快」。那当然快。

Lighthouse 说 LCP 是谁

更进一步，Lighthouse 直接告诉我们 LCP 元素是哪个：

LCP 元素: <p class="cc-nb-text" id="termsfeed-com---nb-text">

不是文章标题，不是卡片，是Cookie 横幅的说明文字。

时间线是：TTFB 1.76s → DOMContentLoaded → window.load → 横幅脚本（66 KB）异步插入 → 解析执行 → 渲染出那块大文本，大约 12 秒。

而 LCP 会一直记录到「用户首次交互」为止，所以这个晚出现的大块，直接把 LCP 顶到了 12 秒。

修了什么

最直接的一刀：别让横幅排在最后。它原来等 window.load 才加载，我改成 DOMContentLoaded 就加载（脚本本身仍是 async）：

// 改前
window.addEventListener("load", load, { once: true });
// 改后
document.addEventListener("DOMContentLoaded", load, { once: true });

实测（Lighthouse devtools 模式）：

	改前（线上）	改后（本地构建）
性能分	37	49
FCP	3.5s	1.6s
LCP	12.1s	7.2s
LCP 元素	横幅文案	仍是横幅文案

还没解决的：横幅仍然是最大的元素

7.2 秒仍然远超 2.5 秒的「良好」线，而且 LCP 元素没变 —— 只要那块说明文字是页面上最大的元素、又是最晚出现的，它就会一直是 LCP。

两条路，都需要权衡：

把横幅做小：限制文字块宽度/行数（它现在是 351px 高的大块），让正文成为最大元素。风险是同意说明变得不明显。
换掉 TermsFeed：自建一个 2KB 的同意条。66KB 的第三方脚本 + 4 倍 CPU，只为了弹一条 Cookie 提示，性价比很低。风险是合规：条款文案、偏好中心、与 GA4/Clarity 的联动都要自己实现。

我倾向第二条，但它动的是合规相关的部分，需要你确认后再做。

三条教训

1. 测量脚本的"隐含条件"必须写下来。 我那行 host-resolver-rules 是三个月前为了修代理超时加的，早就忘了。它悄悄改变了被测对象。现在我在脚本头部固定写一行注释：「本模式会阻断所有第三方域名，只用于隔离自有资源的性能」。

2. 换一个工具复核。 同一个站点、同一台机器，Lighthouse 和我的脚本差 6 倍 —— 不是谁错了，是测的东西不同。两个数字都有价值，但必须知道各自的前提。

3. 永远看 LCP 元素是谁。 数字只是结果，「谁成为了 LCP」才是病因。这次如果不是 Lighthouse 告诉我那是 Cookie 横幅，我可能会去优化图片和字体。

小结

这轮的收获不是"优化了 5 秒"，而是发现自己的测量方法在骗自己。前面几篇里那些好看的数字（FCP 1.4s / LCP 1.9s / 41 个请求）都是真的，但含义是「排除第三方之后」——等于给站点做了一次「断网测试」。

真实场景的数字是：LCP 7.2s（横幅修好后）、TBT 1.5s、83 个请求 / 1MB。接下来的工作很清楚：把第三方从关键路径上撤下来，而不是继续优化我自己的 CSS。

同类的测量陷阱还有一次：和 Cookie 横幅抢 LCP里那三次尝试，有两招其实没用。

我的博客向陌生人暴露了多少信息

Sat, 24 Oct 2026 13:20:00 GMT

写上一篇第三方请求审计时我意识到一件事：「我的站」暴露的不止是页面内容。任何人只要会 curl、会查 DNS、会搜证书日志，就能拼出一张比你想象中完整的地图。

这篇把三层公开面逐一查了一遍，最后修掉了一个真问题。

第一层：证书透明度日志

每次给域名签证书，签名记录都会进 CT 日志，而且永久公开。查一下 juluo.work：

翻出来 18 个名字，去掉泛域名后是 13 个具体子域：api、dak、docker、dok、git、hd、ht、mail、p、t、blog、send，还有一个 juluo.juluo.work。

这些里有一半是早就删掉的测试子域（docker、dok、dak、hd、ht）—— 我从来没主动公开过它们，但它们躺在 CT 日志里，任何人都能查到，并且可以顺手扫一遍。

⚠️ 更要紧的是：扫出来之后能不能被打。我给每个名字都 dig 了一遍：

全部都有解析 —— 都走 *.juluo.work 的通配符，指向优选域名

也就是说，扫 docker.juluo.work/.env 这种请求不会得到 NXDOMAIN，而会打到我的边缘节点上。这解释了 Cloudflare 日志里那些每天几十次的 /.env、/.ssh/id_rsa 探测（全部 403）。通配符 DNS 让扫描器把每一个名字都当成活主机。

第二层：DNS 里的"业务指纹"

DNS 是公开数据库。翻一遍 TXT / MX，能看出你用了哪些服务：

记录	能看出什么
`MX juluo.work → route1-3.mx.cloudflare.net`	邮件走 Cloudflare Email Routing
`MX send.juluo.work → feedback-smtp...amazonses.com`	发信用 Amazon SES
`TXT resend._domainkey` / `cf2024-1._domainkey`	同时接过 Resend 与 Cloudflare 发信
`TXT _dmarc → p=none`	只监控不拦截（下一步该收紧）
`TXT google-site-verification` / `edgeonereclaim` / `_esaauth`	接过 Google 站长、腾讯 EdgeOne、阿里 ESA

这些都不算"泄露"，但它们是基础设施指纹：一个熟练的人看完就知道你的邮件怎么发、CDN 用了几家、验证过哪些平台。

第三层：页面本身

页面是最容易被忽略的一层 —— 它对外主动发出信息。

项	值	是否算问题
QQ 号	`wpa.qq.com/msgrd?...&uin=1576586736`	联系方式，本来就公开（我主动放的）
GA4 ID	`G-C3WKKH0NPV`	公开无妨（只能往里灌垃圾数据）
Umami 站点 ID	`842d980c-…`	分享用，本来就公开
头像	`q2.qlogo.cn/headimg_dl?...&spec=0`	有问题

前三个是设计如此，最后一个不是。

真正要修的那一条：头像

头像的问题是三合一的：

URL 里带着 QQ 号 —— 虽然是联系方式，但"每个访客的浏览器都会主动连腾讯"这件事没写在任何地方；
一张 107 KB 的图，只为显示 254px；
favicon 复用同一个地址，所以一次访问要发 1~2 个请求到 q2.qlogo.cn。

于是我在构建期把它取回来，压成三档放进仓库：

# 640 / 320 / 140 三个尺寸，WebP
avatar-640.webp   32.3 KB
avatar-320.webp   14.7 KB
avatar-140.webp    4.6 KB   ← favicon

Profile.astro 里用 srcset 让浏览器按 DPR 自己挑：

<img src="/assets/avatar/avatar-640.webp"
     srcset="/assets/avatar/avatar-320.webp 1x, /assets/avatar/avatar-640.webp 2x" />

改完的实测：

线上页面 qlogo 引用: False
头像 src: /assets/avatar/avatar-640.webp
srcset:   /assets/avatar/avatar-320.webp 1x, /assets/avatar/avatar-640.webp 2x

收益：外部请求 0 个、头像 106.8KB → 32.3KB（1x 下 14.7KB）、favicon 4.6KB。 隐私政策里「头像取自 QQ 头像服务」那句也同步改成了「已本地化」。

没改、但建议盯着的两件事

1. DMARC 还是 p=none。 意思是「收到伪造我域名的邮件只报告、不拦截」。收紧到 p=quarantine 能挡掉大部分伪造，但要先确认自己的发信链路（SES / Resend / Cloudflare）SPF、DKIM 都对齐，否则会误伤自己的邮件。这条我没动 —— 涉及邮件可达性，得你先确认。

2. 那 13 个子域要不要清理。 现在它们全靠通配符"假装存在"。如果其中某个将来真的挂服务（比如 git.），记得别留下没人管的记录 —— 子域接管的典型成因就是"记录还在、服务没了"。

一份可复用的自查清单

证书日志：crt.sh/?q=%25.<你的域> 看有哪些名字被记住了（包括你以为删掉的）；
DNS：dig TXT/MX 一遍，看能推出多少业务信息（DMARC 策略尤其要看）；
通配符：有 *. 记录就假设所有子域都会被扫，别把"没有服务"当成"没有暴露"；
页面请求：开 DevTools 数一遍对外请求，每个都问「它必须存在吗」；
页面标识：统计 ID、联系方式、图片外链，逐项确认是「我主动公开的」还是「顺手带上的」。

小结

静态博客的优势是没有后端数据，但公开面依然有三层：证书、DNS、页面。

这次审计最值钱的收获不是发现什么惊天漏洞，而是把「我以为」变成了清单：QQ 号是主动放的、统计 ID 无所谓、头像外链则完全没必要。少一个外部请求、少 90KB，同时也少一条"每个访客都在替我连腾讯"的暗线。

随机图当封面：一张 250KB，我没让它进列表

Sat, 24 Oct 2026 13:00:00 GMT

文章写完忘了配图，列表卡片就空一块。随机图 API 看起来很诱人：image: random 一行配置，每篇文章自动有张不一样的封面。我实测了一下那张图，最后决定不把它放进列表。

三种封面方案

方案	做法	代价
手写静态封面	每个 `public/assets/images/posts/<slug>/cover.webp`	每篇文章要多做一张图
构建期生成	用脚本按标题生成（我做过封面生成器）	要写脚本，风格统一但缺少变化
运行时随机图	`image: random`，浏览器去第三方接口取	别人的服务器 + 别人的体积

本站的模板支持第三种：image: random 时，卡片渲染的不是一个本地文件，而是一次外部请求。

它到底返回了多大一张图

curl -sI https://pic.060730.xyz/ri/h/42.webp

关键三行：

Content-Length: 256098                          ← 250 KB
Cache-Control:  public, max-age=0, must-revalidate
CF-Cache-Status: HIT                            ← 边缘有缓存，但浏览器每次都要问

max-age=0 意味着浏览器每次访问都要回来验证一遍。它不像我在缓存那篇里给 /_astro/ 加的 immutable —— 那张图永远处于"可能变了"的状态。

算一笔账

项目	数值
首页卡片数	10
单张随机图	250 KB
一次访问的封面流量	2.5 MB
本站自己的配图（已压缩 + 长缓存）	平均 70 KB

对比之下，我这 19 篇文章的 51 张配图一共 3.63 MB，全部加载一遍比首页挂满随机图还省。

而且这 2.5 MB 还有一个隐含成本：它是串行增加的——卡片进入视口才加载，用户往下滚就一直有请求打出去，而每张都不便宜。

那随机图什么时候合理

不是不能用，而是别用在"列表默认"。我总结的边界：

✅ 单篇文章的封面：一页就一张，250 KB 可以接受（还记得加 loading="lazy"）；
✅ 工具页/画廊的占位：用户明确在看图，愿意等；
❌ 首页列表的默认封面：10 张起步，成本 ×N；
❌ 移动端优先的站点：2.5 MB 在 4G 上就是几秒。

真要在列表里用，正确的做法是让接口返回缩略图（比如再压到 30 KB、宽度 400），并且给它一个正常的 Cache-Control。这两件事都得改服务端，改不了就别用。

兜底：图挂了怎么办

外部图片还有一个绕不开的问题：对方挂了或者改规则了。本站的处理是 onerror 时隐藏图片、保留文字卡片：

<img src={image} onerror="this.style.display='none'" />

这样最坏情况是"卡片没有封面"，而不是"卡片里一个破图图标"。说实话，这个兜底本身也说明了外部图片的定位：锦上添花，不是必需品。

小结

随机图是很典型的"看起来免费"的东西：省了自己做图的工夫，代价转移到了访客的流量和你的依赖清单上。

三条结论：

列表默认不要挂 250 KB 级的随机图，成本按卡片数线性上升；
单篇封面可以接受，配上 loading="lazy"；
判断标准很简单：这张图属于"内容"还是"装饰" —— 装饰性的东西不该占据首屏流量的头几名。

我现在的做法是：文章有配图就用本地压缩好的 WebP（平均 70 KB、长缓存），没有就让卡片干净地只显示文字。空一块，比 2.5 MB 划算。

三层缓存各自为政：我的静态资源被一行 Cache-Control 拖慢

Sat, 24 Oct 2026 12:40:00 GMT

缓存这件事最容易产生「我以为」：以为 CDN 会缓存、以为浏览器会记住、以为 max-age 越大越好。真正会发生什么，只能看响应头。

我写了个脚本抓自己站的缓存头，第一遍就发现：连文件名带内容哈希的 CSS/JS，都被设成了 max-age=0。

三层缓存，各管一段

一个静态站请求要走三层，每层的依据不同：

层	依据	看什么
浏览器	`Cache-Control` / `ETag` / `Last-Modified`	要不要发请求、发条件请求还是全新请求
Cloudflare 边缘	自己的缓存规则 + 源站头	`cf-cache-status: HIT/MISS`、`age`
源站（Worker 静态资源）	部署时生成的头	上面的 `Cache-Control` 就是从这一层出来的

关键点：浏览器和边缘看的是同一行 Cache-Control，但它们的判断逻辑不同。Cloudflare 会把 max-age=0 的资源也缓存（cf-cache-status 照样 HIT，它靠自己的 TTL 与 revalidate 策略），而浏览器则会老老实实每次都回来问一句。

问题：哈希命名的资源也被设成 max-age=0

我的构建产物是这样的：

/_astro/MainGridLayout.C94uCSmW.css   ← 文件名里的 hash 就是内容指纹
/_astro/page.DkKPsu5I.js

这种命名方式天然支持永久缓存：内容一变，文件名就变，旧文件永远不会被误用。合理的头是：

Cache-Control: public, max-age=31536000, immutable

但实际抓到的全是：

Cache-Control: public, max-age=0, must-revalidate

这行对 HTML 是对的（内容会变，必须验证），对哈希资源就是浪费：每次进页面都要回源验证一遍 CSS/JS，即使它们一年都不会变。

另外还发现：HTML 页面没有 ETag（/、文章页都没有），意味着连"条件请求省流量"的机会都没有 —— 每次导航都是全新下载。而 robots.txt、sitemap.xml、CSS、JS 都有 ETag，带 If-None-Match 会正确返回 304。

修法：给 /_astro/ 单独加一条响应头规则

源站是 Cloudflare Workers 的静态资源模式，我改不了它的默认头。但 Cloudflare 的 Response Header Transform 规则可以覆盖：

表达式：starts_with(http.request.uri.path, "/_astro/")
动作：  set cache-control = public, max-age=31536000, immutable

用 API 一秒钟就能建好：

curl -X PUT \
  "https://api.cloudflare.com/client/v4/zones/$ZONE/rulesets/phases/http_response_headers_transform/entrypoint" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  --data-binary @rule.json

{
  "rules": [{
    "action": "rewrite",
    "action_parameters": {
      "headers": { "cache-control": { "operation": "set", "value": "public, max-age=31536000, immutable" } }
    },
    "expression": "starts_with(http.request.uri.path, \"/_astro/\")",
    "description": "Astro build assets immutable cache"
  }]
}

生效后的实测：

/_astro/*.css  -> cache-control: public, max-age=31536000, immutable
/_astro/*.js   -> cache-control: public, max-age=31536000, immutable
/              -> Cache-Control: public, max-age=0, must-revalidate
/robots.txt    -> Cache-Control: public, max-age=0, must-revalidate

HTML 保持 max-age=0 是故意的：页面内容每天都在变，用 ETag 验证比"缓存十分钟"更安全。

两个平台细节（写规则前值得知道）

1. 免费套餐不能用正则。 我第一版写的是 http.request.uri.path matches "^/_astro/"，直接被拒：

not entitled: the use of operator Matches is not allowed,
a Business plan or a WAF Advanced plan is required

换成 starts_with(...) 就行 —— 对路径前缀判断来说完全够用。

2. 规则只对「到达边缘的请求」生效。 如果资源本身被浏览器缓存着（同一个 URL、未过期），请求根本不会到 Cloudflare，规则也就无从生效。所以验证时要么换 URL（构建产物 hash 变了自然会换），要么在 DevTools 里勾"Disable cache"。

一套可以照抄的判断表

资源	建议的 Cache-Control	原因
哈希命名的构建产物（`/*.abc123.css`）	`public, max-age=31536000, immutable`	内容变则文件名变，永久缓存安全
HTML	`public, max-age=0, must-revalidate` + ETag	内容常变，靠 ETag 走 304
不哈希的图片	`public, max-age=86400` 以上	很少变；换图时改文件名
robots / sitemap / RSS	`max-age=0` 或按更新频率	搜索引擎需要拿到最新内容

小结

缓存不是"设一个数"就完事，而是三层各自判断的结果。这次改动很小（一条规则、两个表达式），但它解释了为什么我的第二次访问和第一次一样慢 —— 浏览器从来没记住过那些哈希资源。

验证缓存改动只需要两个动作：抓两遍响应头（看 Cache-Control 与 cf-cache-status）、发一次条件请求（看是否 304）。两个都符合预期，才算真的缓存上了。

首屏优化的完整背景（埋点延后、头像取图、关键 CSS 瘦身）见首屏从 392KB 砍到 59KB。

同一条链路上还有一个更顽固的对手：Cookie 横幅抢走了 LCP，过程见和 Cookie 横幅抢 LCP。

图片格式的收益边界：PNG → WebP → AVIF 实测

Sat, 24 Oct 2026 12:20:00 GMT

「AVIF 比 WebP 小 50%」这句话在中文技术圈流传很广。我拿自己站上 12 张真实配图做了实验，结论是：同画质下平均省 35%，但如果你按"质量参数相同"去比，AVIF 甚至可能更大。

差异在于怎么定义「同画质」。这篇文章把方法、数据和结论都写清楚。

第一轮：按质量参数比，结论是错的

最直接的做法是「WebP quality=80 vs AVIF quality=80」。实测下来 AVIF 反而更大（上表 q75 那一列已经能看出趋势，q80 更明显）。

原因很简单：两种编码器的 quality 不是一个标尺。WebP 的 80 与 AVIF 的 80 对应的视觉质量完全不同，直接比体积没有意义。

这一轮唯一有效的结论是：AVIF 的等视觉质量点大概在 q50~q60 附近，而不是 q75+。

第二轮：用 PSNR 对齐画质

正确做法是先定义「什么算同画质」，再在那个点上比体积。我用 PSNR（峰值信噪比）当判据：

参考图 = 仓库里现成的 WebP（它本身已经是有损压缩过的，作为基准）；
对每张图用 AVIF 从 q40 到 q80 逐档编码，算它与参考图的 PSNR；
取第一个 PSNR ≥ 38 dB 的档位 —— 38 dB 大约是「并排看、放大到 100% 也看不出差别」的水平。

结果：

图片	WebP q80	同画质 AVIF	节省	编码耗时
78 KB 网页截图	79.7 KB	q50 → 46.1 KB	42%	138 ms
144 KB 网页截图	183.9 KB	q60 → 152.1 KB	17%	146 ms
31 KB 手机截图	31.9 KB	q50 → 19.1 KB	40%	167 ms
23 KB 终端截图	23.7 KB	q50 → 14.4 KB	39%	58 ms

平均规律：文字/界面类截图省 35%~42%，照片类只省 17% 左右。 这很符合直觉：AVIF 的优势在大面积平滑渐变与照片，而截图里全是锐利的文字边缘，省不出那么多。

编码耗时方面，1400×900 一张图 WebP 约 113 ms、AVIF q60 约 144 ms（1.3 倍）。对构建期批量处理来说完全可以接受。

那为什么我还在用 WebP

三个理由，按权重排：

1. 收益要看绝对值。 我站上单张图平均 70 KB（51 张 / 3.63 MB），省 35% 就是每张省 25 KB、全站省约 1.2 MB。而文章页一次只加载 3~5 张图 —— 单页实际省下 100 KB 左右。这 100 KB 值得做，但不值得为它牺牲"一套格式、一个脚本"的简单性。

2. 兼容性还差一点。 AVIF 在 Chrome 85+、Firefox 93+、Safari 16.4+ 才支持。2023 年之后的浏览器都没问题，但没有一个通用格式做不到的兜底：老浏览器打开就是空白图。

3. 一部分图是从截图直接来的。 截图（大量锐利文字）恰好是 AVIF 收益最低的一类，而它是我最主要的图源。

什么时候值得上 AVIF

如果你符合下面两条以上，就该上：

站点图片总量大（几十 MB 以上），或单张图很大（> 500 KB）；
图片以照片/插画为主，而不是文字截图；
访客主要在移动网络；
已经有 <picture> 或图片组件，能同时输出两种格式。

写法就是标准的 <picture> 回退：

<picture>
  <source srcset="/img/cover.avif" type="image/avif">
  <source srcset="/img/cover.webp" type="image/webp">
  <img src="/img/cover.jpg" alt="封面" width="1200" height="675" loading="lazy">
</picture>

浏览器会挑它支持的第一个格式，两种都压好、谁支持谁用，这才是不牺牲兼容性的做法。

一个容易被忽略的对比维度

除了体积，还有两个数字值得一起看：

维度	WebP	AVIF
同画质体积	基准	省 17%~42%
编码耗时	113 ms	144 ms（1.3×）
解码耗时	快	略慢（移动端更明显）
浏览器支持	全平台	2023 年后

解码耗时这一项常被忽略：AVIF 的解码比 WebP 重，在低端手机上首屏图片渲染可能反而更慢。省下的字节要能抵过解码代价，才算真的赚。

小结

三条可以直接用：

别按质量参数比：WebP 80 与 AVIF 80 不是同一个东西，要先定义"同画质"（我用 PSNR ≥ 38 dB）；
截图与照片要分开看：截图省 35%~40%，照片只省 15%~20%；
决定因素是绝对字节数：单页省 100 KB 值得做，但为它引入两套格式、两套脚本，就不一定了。

我目前的结论是：继续用 WebP 单格式，等图片量再涨或者需要面向移动网络时，再切到 <picture> + 双格式。到时候这篇文章里的数字可以直接拿来算收益。

每一步怎么执行写在文章配图流水线里，两篇可以对照着看。

封面图该用多大的图、要不要用随机图接口，见随机图当封面那篇。

静态博客接评论：Giscus 的配置、主题联动与三个坑

Sat, 24 Oct 2026 12:00:00 GMT

静态博客没有后端，评论只能挂在别人身上。我选的是 Giscus：把评论存进 GitHub Discussions，访客用 GitHub 账号登录发言。

选它的理由只有两条，但都很硬：

不用自己存任何用户数据 —— 没有邮箱、没有昵称、没有密码，登录和身份全在 GitHub 那边；
数据是你的 —— 评论就是仓库里的 Discussion，随时可以导出、迁移，甚至换一个前端重新渲染。

六个字段，各有各的用处

export const giscusConfig: GiscusConfig = {
    enable: true,
    repo: "juluowork/giscus",          // 评论存在哪个仓库
    repoId: "R_kgDOPdSugg",            // GraphQL node id（不是仓库名）
    category: "Announcements",         // 存到哪个 Discussion 分类
    categoryId: "DIC_kwDOPdSugs4CuINO",// 分类的 node id
    mapping: "pathname",               // 页面与 thread 的对应规则
    lang: "zh-CN",
    theme: `https://${customDomain}/css/giscus.css`,
};

两个 id 最容易填错：repo 和 category 只是给人看的，真正的依据是 repoId / categoryId（GitHub GraphQL 的 node id）。填错的表现是"评论区加载出来了，但一直转圈 / 报 repo not found"。

mapping: "pathname" 意味着一个 URL 路径对应一个 thread。这一条后面会变成坑。

主题联动：iframe 拿不到父页面的样式

评论区是 iframe，它里面的 CSS 与你的站点完全隔离。所以"自动跟随亮/暗色"不能靠继承，只能靠传参。

Giscus 支持 theme 传一个样式表 URL，它会把这个 CSS 注入到 iframe 内部。于是我把主题色、背景色、字体都写进自己站点的 /css/giscus.css，再让 iframe 指向它：

/* public/css/giscus.css 的一部分 */
main { --color-canvas-default: transparent; }
.gsc-comment-box { border-radius: 0; }

这样做的好处是：换主题不用改 Giscus 配置，因为样式文件本身就在你的仓库里。代价是改样式之后要让访客刷新（iframe 的 CSS 会被浏览器缓存）。

怎么验证「评论真的加载了」

「页面上有个框」不等于评论能用。我用的验证方法是量高度 + 看 iframe 参数：

await page.goto(url, { waitUntil: "load" });
await page.waitForTimeout(6000);
const iframe = document.querySelector("iframe[src*='giscus']");
console.log(iframe.src);                          // 检查 origin / theme 参数
console.log(iframe.getBoundingClientRect().height); // 初始 150，加载完 372

实测结果：

初始占位高度 150px（脚本还没跑完）；
滚到底、等 6 秒后 iframe 长到 372px，说明评论 UI 真的渲染了；
iframe 的 src 里带着 origin=https://blog.peroe.cn/posts/xxx/#giscus-container 与 theme=https://blog.peroe.cn/css/giscus.css。

这个"看高度"的方法很笨，但比截图肉眼看更可靠 —— 因为加载失败时 iframe 停在 150px，肉眼看起来只是"评论区有点矮"。

三个坑

1. 仓库迁到组织之后，必须重装 Giscus App。

我把评论仓库从个人账号迁到了 juluowork 组织，结果评论区一片空白。原因是 Giscus 的 GitHub App 授权是按账号的：个人账号装过的授权，不会覆盖组织下的仓库。重新到 https://github.com/apps/giscus 选组织安装即可，repoId / categoryId 都不用改。

2. 改 slug 等于换了一个 thread。

mapping: "pathname" 用路径做键。我把一篇文章的 slug 从 xxx 改成 yyy，评论就"消失"了 —— 其实是新路径对应了一个新的 Discussion，旧评论还在旧 thread 里。如果文章已经有人评论，改 slug 前先想想这条；实在要改，可以在旧 thread 留一条指向新地址的说明。

3. iframe 是异步加载的，会给页面带来布局跳动。

评论脚本在页面底部注入 iframe，高度从 0 涨到几百像素 —— 如果它上面还有内容，整块会被顶下去（和上次那个 CLS 同源）。解决办法是给容器一个 min-height，或者让脚本在滚动到附近时才加载。

小结

Giscus 的接入成本很低（填六个字段、贴一段脚本），但有三件事值得在接入时就定下来：

评论仓库的归属：放在组织下比个人账号更稳，但要记得重装 App；
mapping 规则：pathname 最直观，但要接受"改 slug = 换 thread"；
验证方式：量 iframe 高度、看 src 参数，比截图看一眼可靠。

顺带说一句：这个站的评论数据（0 条）在 juluowork/giscus 仓库的 Discussions 里，如果要迁移或备份，直接导出就是 Markdown。

评论是本站第三个「把访客交给别人」的地方，完整清单在第三方请求审计。

Astro 静态站的三个隐形约定：CSS 是全局的

Sat, 24 Oct 2026 11:40:00 GMT

用 Astro 写静态站很省心，但它的默认行为里有三条不写在报错里、也不写在文档首页的约定。这三条我都在这两周里踩过，代价分别是：一个整站不跑、多下 200KB 关键 CSS、以及一次错误的性能/SEO 结论。

约定一：`<script>` 默认不是你想的那种 script

我在接 Cookie 同意横幅时写了这样一段：

---
import { cookieConsentConfig } from "@/config";
---
<script>
  // 以为会原样输出到页面里
  cc.run({ website_name: cookieConsentConfig.websiteName });
</script>

结果浏览器报 cookieConsentConfig is not defined，横幅整条不出现。

原因：Astro 会把没有 is:inline 的 <script> 当成模块打包（type="module"，走 Vite 的模块图）。打包后它运行在独立作用域里，拿不到 frontmatter 的变量。想让它和 frontmatter 共享数据，要么用 is:inline 让它原样输出，要么用 define:vars 显式注入：

<script is:inline define:vars={{ cookieConsentConfig }}>
  cc.run({ website_name: cookieConsentConfig.websiteName });
</script>

同一个坑在 JSON-LD 上还有变体：结构化数据必须用 set:html 输出，不能用 {JSON.stringify(x)}，否则引号会被转义成 "，搜索引擎读到一段坏 JSON。

自检：grep -c "is:inline" dist/index.html —— 如果一个都没有，说明你站点里所有 inline 脚本都变成了模块，任何"页面里的小脚本"都会失效。

约定二：CSS import 默认是全局的

这条最贵。

我在布局里 import 了公式与代码高亮的样式：

// src/layouts/Layout.astro —— 每个页面都会经过这里
import "katex/dist/katex.min.css";
import "prismjs/themes/prism-tomorrow.css";

看起来很自然：文章页要公式、要代码块。但 Astro 会把布局链上的 CSS 合并进一份全站关键 CSS，于是首页、归档、工具页统统要多下这份样式 —— 而首页连一个公式都没有。

更糟的是，这份关键 CSS 里还有上游模板遗留的编辑器样式（@import "@toast-ui/editor/dist/toastui-editor.css"）：项目里根本没人 import 那个编辑器的 JS，也没有任何 .toastui-editor-* 的 DOM，但它的样式一直在被打包。

按选择器前缀统计，311.8 KB 的关键 CSS 是这么构成的：

修法两条：把只在文章页用的样式移到文章页，把模板遗留的死 @import 删掉。结果首页关键 CSS 从 311.8 KB 降到 104 KB，文章页看不出任何差别。

自检：打开构建产物里的 HTML，数一下 <link rel="stylesheet"> 与它们的体积，再问一句「这个页面真的用得到这些样式吗」。工具页、首页、文章页的 CSS 才应该不同。

约定三：`dist/` 从不清空

我为 SEO 体检写了个脚本，扫 dist/**/*.html。某次扫出来 28 个页面，其中一个是 /t/：

/t/   - canonical 指向 https://i.juluo.work/
      - 缺 description / 缺 h1 / 缺 JSON-LD

但线上访问它明明 404。原因是：dist/ 在两次构建之间不会被清理，/t/ 是几天前删掉的页面残留的产物。我的审计脚本于是给了一份「本地有问题、线上不存在」的结论。

Cloudflare 从干净仓库构建，所以线上是对的；但本地做任何基于产物的分析（审计、体积统计、性能测试）之前，都该先删 dist/。

自检：ls dist/*/index.html 对着 src/pages 数一遍；更省事的做法是每次分析前跑一次 rm -rf dist && pnpm astro build。

附带的第四个坑：0 不等于「没有数据」

这个坑不是 Astro 的，但同样隐形，而且就在这一轮被截图暴露出来：新发布的文章卡片上显示「0 次」，而自建统计里明明已经有浏览记录。

原因在合并逻辑：

// 之前：只有 Umami 返回 undefined 才认为"缺口"
const missing = paths.filter((p) => umami?.paths[p] === undefined);
// ...
const all = { ...selfHosted, ...umami };   // umami 的 0 会盖掉自建的正数

Umami 对新路径返回的是「存在但为 0」，不是「没有这条记录」。于是自建侧的数被当成"已经由 Umami 覆盖"，永远显示 0。修法是把 0 也当作缺口，并在合并时让自建的正数优先：

const missing = paths.filter((p) => {
    const v = umami?.paths[p];
    return v === undefined || v === 0;      // 0 也算缺口
});

const all = { ...(selfHosted ?? {}) };
for (const [p, v] of Object.entries(umami?.paths ?? {})) {
    if (v > 0 || all[p] === undefined) all[p] = v;   // 0 不覆盖已有的正数
}

教训：「查不到」和「查到了 0」是两件事。API 用 0 表示"没有数据"时，任何"缺省才补"的兜底逻辑都会失效。

三条约定合起来的一句话

Astro 把「布局、样式、脚本、产物」都当成可优化的整体来管，所以它的默认值是为产物服务的，不是为「你以为的作用域」服务的。判断方法很简单：

脚本：产物里的 <script> 有没有 type="module"？
样式：产物里每个页面引用的 CSS 是不是同一份、多大？
产物：你分析的是不是一次干净构建的结果？

这三问都答得出来，Astro 的「隐形约定」就不隐形了。

同一条「作用域」思路也解释了缓存那篇的结论：内容哈希命名的资源应当永久缓存。

同一个站的两套统计，为什么差了 2.7 倍

Sat, 24 Oct 2026 11:20:00 GMT

本站装着两套访问统计，而且都是我自己在用的：

Umami Cloud —— 从 2025 年就在记，跨域名迁移后历史保留；
自建 Worker + D1 —— 一个 tracker.js 加一张 pageviews 表（pathname 主键 + views）。

按理说它们看的是同一批访客。但把时间窗对齐到「迁移到 peroe.cn 之后」，同一段时间里首页被记了 67 次和 180 次。

先对齐口径，再谈差异

不同口径比大小没有意义，所以我做了三件事：

同一个时间窗：都从 2026-10-06（迁到新域那天）开始算 —— Umami 里还留着旧站 blog.peroe.top 的历史，不截断的话它当然更大；
同一个指标：都取 pageview（页面浏览次数），不拿 visitors / visits 去比；
同一个站点：都只看 blog.peroe.cn 下的路径。

对齐之后，全站是 267 对 294 —— 差 10%，还算接近。但单个页面差得离谱：首页 67 vs 180（2.7 倍）、/posts/hello-world/ 1 vs 7（7 倍）。

实验：把 Umami 的域名挡掉

第一个怀疑对象是广告拦截器。cloud.umami.is 是个知名统计域名，uBlock、AdGuard 之类默认就会拦；而 t.peroe.cn 是我自己的域名，任何拦截列表里都没有。

验证方式很直接：用 Playwright 打开首页，把 *.umami.is 的请求全部 abort（模拟装了拦截器），然后看自建计数的表现：

await page.route("**://*.umami.is/**", (route) => route.abort());   // 模拟拦截

const before = 179;   // 实验前 D1 里 "/" 的 views
await page.goto("https://blog.peroe.cn/");
await page.waitForTimeout(9000);
// 实验后：D1 的 "/" 变成 180

结果：被拦下的 Umami 请求 2 个、自建计数 +1、Umami +0。

也就是说，装了拦截器的访客在两套统计里只留下一条记录 —— 他们的每一次访问，Umami 都看不见，而自建计数看得见。中文互联网上装拦截器的比例不低，这足以解释绝大部分差距。

另外三种会放大差距的机制

除了拦截器，还有三个我在实现里能确认的因素：

1. 脚本加载时机不同。 我把 GA4 与 Clarity 延后到 requestIdleCallback 才加载（见首屏优化那篇），Umami 的 script.js 也在那次改造后跟着延后；而 tracker.js 是页面一解析就执行。秒退的访客在 Umami 这边可能根本没等到 idle 就离开了。

2. bot 过滤不同。 Umami 会按 User-Agent 过滤已知爬虫；我的 tracker.js 只有一行 fetch，不做任何判断。这个站被扫描器盯得挺紧（Cloudflare 日志里每天都有几十个伪装 Googlebot 的请求打 /.env），它们大多不执行 JS，但只要有能跑 JS 的抓取器，自建计数就会虚高。

3. 我自己的自动化访问。 写这几篇文章的过程中，我在这台机器上把首页加载了上百次（截图、测性能、验证结构化数据）。每一次都是真实的一次 /send，也都有机会被 Umami 记上 —— 但它俩对"这次访问"的容忍度不同：我经常在页面刚 load 完就关掉浏览器，Umami 的 idle 回调还没跑。

那到底该信哪个

我的结论是：两个都不"错"，它们量的是不同的集合。

Umami 更接近"人"：过滤爬虫、要求脚本加载完成，数字偏低但更像真实读者；
自建 D1 更接近"请求"：只要页面跑了 JS 就记，数字偏高但能覆盖被拦截器挡掉的那部分。

所以我把它们当区间用：真实访问量大概在「Umami 的 267」到「D1 的 294」之间，偏向 Umami 那一侧（因为拦截器用户毕竟还是少数，而我的自动化访问占了不少）。

展示哪个数字

站点侧栏显示的是 Umami 的数字：

理由有两个：一是它跨域名迁移后历史连续（从 2025 年记到现在），读者看到的是一条平滑上升的曲线，而不是某天突然归零；二是它过滤了爬虫，数字更"干净"。

自建 D1 则退居兜底 —— 当某个路径 Umami 还没有数据（比如刚发布几分钟的新文章）时，才用它补一下。

如果你也想接两套统计

三条建议：

先对齐口径再比：截断时间窗、只比同一个指标，否则会得出"某套统计坏了"的错误结论；
把差异当成信息：两套的差就是"被拦截/被过滤的比例"，这本身比单一数字更有意思；
展示时选一个口径并写清楚：读者不需要知道你有两套统计，但你自己要知道屏幕上那个数字代表什么。

顺带一个实现细节：D1 的 HTTP 查询有几秒的读延迟，我刚发完一条就查会看不到。第一次实验我因此以为"自建计数没记上"，多等几秒才发现早就 +1 了 —— 排查计数问题时，先怀疑读延迟，再怀疑写入。

这些数字最终怎么显示到页面上，见浏览量统计那篇；完整的第三方清单见审计那篇。

文章配图流水线：截图、压成 WebP、随构建分发

Sat, 24 Oct 2026 11:00:00 GMT

写一篇带实测的技术文章，大概一半时间花在图上：截哪几张、截图里的数字对不对、压完还看不看得清、放进哪个目录。这些事重复十几次之后，必须有流水线——否则每次都要重新想一遍。

我这 13 篇文章一共 51 张配图、3.63 MB，全部走同一条流水线。规则只有四条。

规则一：截图必须是真实页面的

不做示意图、不用拼贴。写性能就打开 Chrome 的 Performance 面板或跑真实脚本，写 Cloudflare 就截控制台里的真实配置。文章里说「实测」的每一个数字，都要能在截图里找到。

截图工具是 Playwright + 本机 Chrome，必须 --headed —— 无头模式会被 Cloudflare 的浏览器校验拦住，截出来是一片空白。常用参数就几个：

# 整页截图，等 3 秒让懒加载与动画稳定，顺手隐藏 Cookie 横幅
node shot.mjs --url https://blog.peroe.cn/posts/xxx/ \
  --out ./02-post.png --width 1280 --height 900 --scroll 700 \
  --hide "#termsfeed-com---nb" --wait 3500

--hide 那一条是血泪：Cookie 横幅固定在底部，不藏掉会挡住正文的结论部分。

规则二：文件名就是出场顺序

配图放在 public/assets/images/posts/<slug>/，目录名与文章 slug 完全一致，文件按正文出现顺序编号：

public/assets/images/posts/blog-image-pipeline/
├── 01-convert.webp     ← 正文里第一张出现的图
├── 02-post.webp
└── 03-weight.webp

正文里用绝对路径引用（以 / 开头，走 public 目录）：

![压缩实测：2073KB → 357KB](/assets/images/posts/blog-image-pipeline/01-convert.webp)

目录名和 slug 不一致是最常见的 404 来源：文章能构建成功、图片全裂，而且本地开发时因为缓存还可能看着正常。

规则三：统一压成 WebP，宽度封顶

截图先存 PNG（无损、方便复核），再统一转 WebP：

我这批的压缩率是 83%，单张从几百 KB 降到一个屏都不一定用得完的大小。脚本做的事情很简单：Pillow 打开、convert("RGB")、save(quality=80)、限制最大宽度 1500px（截图放大就看不清字了，1500 够用）。

几个经验值：

类型	建议	原因
终端输出 / 表格	宽度 1000~1100、quality 80	等宽字体在高压缩下容易糊
网页截图	宽度 1280~1400、quality 80	再大就是浪费，页面本身按 1200 设计
图表 / 细线	quality 85	细线在 WebP 里最先出现振铃
单张上限	300 KB	超过就该考虑裁掉无关区域

规则四：图进仓库，不走图床

这是被讨论最多的一条。我选择把图片直接提交进仓库，理由是三个「不」：

不会跑图：图床跑路、防盗链、限速、跨域——这些问题全部消失，图片和 HTML 同源、同一套 CDN；
不依赖第三方：访客打开文章时，除了统计与评论，不再有任何外部图片请求；
构建时能校验：图片不存在，构建产物里就是一个 404 的 <img>，本地一看就知道。

代价是仓库体积。所以我给单张设了 300 KB 的上限（当前最大的一张 184 KB），并且只保留文章里真正用到的图——草稿截图、重复截图一律不进仓库。

3.63 MB 对一个博客来说完全可以接受：它随构建分发，不占额外存储、不需要额外域名，也不会因为某个第三方服务挂掉而集体失效。

五个踩过的坑

1. 忘了按顺序编号。写完后插入了一张新图，编号乱了，正文里的 01/02/03 与目录对不上。解决办法是写完先列一遍图的位置，再统一编号。

2. 直接把 PNG 提交了。一张 1280×900 的网页截图 PNG 有 800 KB 到 1.2 MB，同样尺寸的 WebP 只有 40~120 KB。现在 public/ 里不允许出现 PNG 截图。

3. 目录名与 slug 不一致。改 slug 时忘了改目录，图片全 404。现在改 slug 会顺手 git mv 目录。

4. 截图里带着指纹信息。浏览器窗口标题栏、书签栏、系统时钟都可能泄露「这台机器是谁」。要么截图前隐藏，要么裁掉页头。

5. 正文里的数字与截图对不上。有一次脚本重跑后数字变了，正文还写着旧值。现在改完会重新截图，并把数字直接从脚本输出里抄——不要凭记忆写数字。

一条命令的收尾流程

现在的固定动作是这样：

# 1. 截图（headed，藏掉 Cookie 横幅）
node shot.mjs --url <文章地址> --out 02-post.png --width 1280 --hide "#termsfeed-com---nb"

# 2. 转 WebP（顺便限制宽度）
python to-webp.py . --quality 80 --max-width 1500

# 3. 确认体积（单张 < 300KB）
ls -lh *.webp

# 4. 写文章、引用、构建
pnpm astro build --force

四步走完，图的格式、体积、路径、命名就都是确定的——写正文时可以专心在内容上。

小结

配图流水线的价值不在「省时间」，而在让每次的结果一样：同样的命名规则、同样的压缩参数、同样的引用路径。当这些都不需要再想的时候，写文章才真正只剩下「把话说清楚」这件事。

三条可以立刻照抄的规则：真实截图（数字能对上）、顺序编号 + 目录同名（不会 404）、一律 WebP 且单张 < 300 KB（不拖慢文章页）。其余的（工具、参数）按自己的习惯换都行。

格式选择（继续用 WebP 还是上 AVIF）的实测数据在图片格式的收益边界。

静态博客的隐私边界：一次第三方请求审计

Sat, 24 Oct 2026 10:35:00 GMT

「静态站没有后端，所以没什么隐私问题」——这句话只说对了一半。没有数据库、没有登录、没有人存你的手机号，但页面本身可以调外部服务：统计、评论、头像、Cookie 横幅、性能监控……这些多半不是你主动选的，而是跟着模板一起搬进来的。

我写了个脚本把首页与文章页的外部请求全部列出来，结果是：首页向 15 个第三方域发出了 30 个请求。

怎么审：只看「不是我的域名」

思路很朴素：拦截所有响应，凡是 host 不等于自己域名的，按域聚合并统计。核心代码十几行（Node + Playwright）：

page.on("response", (res) => {
    const u = new URL(res.url());
    if (u.hostname === "blog.peroe.cn") return;   // 自己的域跳过
    reqs.push({
        host: u.hostname,
        type: res.request().resourceType(),        // script / image / xhr / fetch
        len: Number(res.headers()["content-length"] ?? 0),
    });
});

// 等 9 秒：埋点脚本是延后加载的，早扫描会漏掉
await page.waitForTimeout(9000);

// 再按 host 聚合打印：${count}× ${bytes} ${host} [${types}]

两个容易漏的地方：

别在 load 事件就收工 —— 埋点、懒加载图片、评论组件都可能在 load 之后才请求，我这里是等了 9 秒；
fetch/xhr 也算 —— 最典型的追踪请求（GA 的 /g/collect、Umami 的 /api/send）都是 fetch，不是脚本。

15 个域都是谁

把结果按「谁发起的」分类，其实很清楚：

类别	域	说明
自己的服务	`t.peroe.cn`	自建浏览量统计（`tracker.js` + `/send`）
内容必需	`q2.qlogo.cn`	侧栏头像（QQ 头像服务）
评论	`giscus.app`	文章页才加载，基于 GitHub Discussions
Cookie 合规	`www.termsfeed.com`	同意横幅脚本
统计	`cloud.umami.is` + `gateway-us.umami.is`	Umami 上报 + 共享数据读取
统计	`www.googletagmanager.com` + `www.google-analytics.com`	GA4（177 KB 的 `gtag.js`）
统计	`www.clarity.ms` + `scripts.clarity.ms` + `c./i./q.clarity.ms`	Clarity 主脚本与上报
平台	`static.cloudflareinsights.com`	Cloudflare Web Analytics（RUM），由 CDN 侧自动注入

这些都是我自己开的、知道的。但列表最后一行是：

1x  browser-update.org  [script]  /update.min.js      ← 模板遗留

这个我从来没开通过。

意外发现：模板自带的「浏览器过旧」脚本

顺藤摸瓜，它在 BodyThirdPartyScripts.astro 里，是一段从上游模板继承下来的代码：

var $buoop = { required: { e: -4, f: -3, o: -3, s: -1, c: -3 }, api: 2024.11, ... };
function $buo_f() {
    var e = document.createElement("script");
    e.src = "//browser-update.org/update.min.js";   // ← 每次访问都会请求它
    document.body.appendChild(e);
}
document.addEventListener("DOMContentLoaded", $buo_f, false);

它做的是「如果你的浏览器太旧，就弹一条提示」。听起来无害，代价是：每个访客打开任何一个页面，都会向 browser-update.org 发一个请求，连带把 IP、User-Agent、Referer 暴露给一个跟本站毫无关系的第三方。

而我这个站本来就需要现代浏览器（用到了 :has()、CSS 嵌套、svh 单位），旧浏览器打开本来就是「样式崩了」而不是「能看但别扭」——为了一条提示，多一个追踪面，不值。

删掉整块脚本和配套的 .buorg 样式（1833 字节），重新扫一遍：

另一个发现：10 个请求只为了显示几个数字

审计里最扎眼的是这行：

10x  gateway-us.umami.is  [fetch]  /api/share/...  /api/websites/...

首页要显示「全站浏览量」和每篇文章的浏览量，而 Umami 的共享接口没有批量查询，只能一条路径一个请求：1 个全站 + 9 篇文章 = 10 个请求。

这是我在浏览量那篇里做过的取舍：要连续的历史数字（Umami 从 2025 年就在记），就得接受 N+1 个请求。如果哪天更在意请求数，可以换成 metrics?type=path 一次拿全站 Top N —— 但那是 UV 口径，和现在展示的 PV 对不上。

写在这里是想说明：第三方请求不只是"隐私问题"，也是"你自己设计的成本"。审计时两种都要看。

隐私页现在写什么

删掉一个脚本之后，我把 /privacy/ 的第三方清单补全了 —— 之前漏写的两个：

Cloudflare Web Analytics：CDN 侧自动注入 beacon.min.js，不使用 Cookie，但会上报页面地址、加载耗时、浏览器信息；
TermsFeed：同意横幅的脚本来源，以及它写入的 cookie_consent_level。

原则很简单：页面上跑了谁的代码，隐私政策里就要有谁。列出域名比写「我们可能使用第三方服务」有用得多，因为访客可以直接对照自己浏览器的网络面板。

一份可以照抄的自查清单

把第三方请求当成待办事项：新装一个评论/统计/字体服务，就顺手跑一次审计；
区分「我选的」和「模板带的」：前者写进隐私政策，后者默认删掉再说 —— 需要再装；
注意延迟加载：等够时间（我用 9 秒）再统计，否则埋点会被漏掉；
连 fetch 一起看：很多追踪走的是 fetch，不是 <script>；
头像、字体、图标也是第三方：它们能看到访客的 IP 与 Referer；
定期复查：模板升级、插件更新都可能悄悄加回东西。

小结

静态博客的隐私优势是真的（没有后端、没有数据库、没有账号体系），但它不等于「零第三方」。这次审计最大的收获不是删掉了一个脚本，而是意识到：你交付的页面是一个请求图，而不是一份 HTML。那张图里有几个节点，值得你每隔一阵子数一遍。

审计脚本我留在本地工具目录里，以后每次加新服务都跑一次；目前第三方已经从 15 个域降到 14 个，剩下的每一个我都能说清它为什么存在。

第三方里最容易被忽略的是评论系统（见 Giscus 那篇）；至于两套统计为什么数字不同，见两套统计对比。

顺着「谁在收数据」再往下想一层，就是我的博客向陌生人暴露了多少信息——证书日志、DNS、页面标识三层。

首屏从 392KB 砍到 59KB，FCP 从 7.4 秒到 2.1 秒

Sat, 24 Oct 2026 09:45:00 GMT

[!TIP] 2026-10-24 后续：又做了两轮 —— 从关键 CSS 里挖出 160KB 编辑器死代码（282KB → 104KB），最后发现 CLS 的真凶是侧栏在 DOM 里排在 <main> 之前、而视觉顺序相反，把侧栏挪到后面后 CLS 直接归零。三项核心指标现已全部进入 Google「良好」区间，详见文末两节。

上一轮做完 SEO 自我体检，顺手用同样的思路量了一次首屏：FCP 7.4 秒、LCP 43 秒、CLS 0.5，而且 LCP 元素居然是 Cookie 横幅的文案 —— 说明打开页面那几秒里，浏览器的注意力全被别的请求抢走了。

[!NOTE] 测量方式：Playwright 驱动本机 Chrome，用 CDP 把网络限到 1.6Mbps / 150ms RTT、CPU 降速 4×（大致相当于一台中端安卓机在 4G 上的体感），再用 PerformanceObserver 采集 FCP / LCP / CLS / 长任务。所有数字都是同一脚本、同一参数、改动前后各跑两遍的结果。

别只看分数，要看「谁在抢首屏」

Lighthouse 会给一个总分，但它不会告诉你 LCP 元素是 Cookie 横幅。我更关心两个问题：首屏到底在等什么、谁把主线程占住了。所以脚本除了打指标，还记录每次请求的字节数与资源类型，以及 LCP 到底落在哪个元素上。

第一次跑出来是这样：

拆开看，问题有四层：

现象	证据
埋点脚本抢跑	`gtag.js` 单个 177.1KB，Clarity 还要再拉一坨；两者都在首屏阶段就开始下
头像和 favicon 用原图	`q2.qlogo.cn` 的 `spec=0` 原图 106.8KB，被下载了两次（头像 + favicon）
关键 CSS 过大	首页要下 311.8KB 的 `MainGridLayout.css`（里面混进了 KaTeX 与 Prism 的样式）
结果	长任务 10~13 个 / 1.7~2.1 秒；LCP 被晚到的 Cookie 横幅顶替

改动一：埋点延后到空闲时段

统计脚本对首屏没有任何价值，但它默认和页面同时开始加载。我把 GA4 与 Clarity 都挪到 window.load 之后的 requestIdleCallback 里再动态注入：

var loadAnalytics = function () {
    if (window.__trackingDenied) return;   // 访客拒绝过就一个字节都不下载

    window.dataLayer = window.dataLayer || [];
    window.gtag = window.gtag || function () { window.dataLayer.push(arguments); };
    window.gtag("js", new Date());
    window.gtag("config", GA_ID);
    var g = document.createElement("script");
    g.async = true;
    g.src = "https://www.googletagmanager.com/gtag/js?id=" + GA_ID;
    document.head.appendChild(g);
};

var idle = window.requestIdleCallback || function (fn) { return setTimeout(fn, 1200); };
if (document.readyState === "complete") idle(loadAnalytics);
else window.addEventListener("load", function () { idle(loadAnalytics); }, { once: true });

这段改动的关键是不能改变行为语义：

统计口径不变 —— pageview 只是晚一两秒上报；
「默认开启、拒绝即停用」不变 —— 加载前再查一次 __trackingDenied，拒绝过的访客一个埋点请求都不会发（我专门用 cookie_consent_level.tracking=false 跑了一遍：0 个请求、ga-disable 为 true、Clarity 未被注入）；
用户中途点「同意」也不需要特判 —— 那时 __trackingDenied 是 false，延迟加载自然会执行。

改动二：头像按 DPR 取图

头像在侧栏里显示宽度最多 280px，但 <img src> 指向的是 spec=0（QQ 头像的原图），实测 106.8KB。qlogo 支持用 spec 指定尺寸，我实测了三档：

spec	实际体积
`spec=0`（原图）	106.8 KB
`spec=640`	52.8 KB
`spec=140`	6.2 KB

于是给它加 srcset，让浏览器自己挑：

const avatarSrcSet = config.avatar.includes("spec=0")
	? `${config.avatar.replace("spec=0", "spec=140")} 1x, ${config.avatar.replace("spec=0", "spec=640")} 2x`
	: undefined;

再加 fetchpriority="low"（头像不该和正文抢优先级）。width / height 本来就有，所以不会引入新的布局偏移。

改动三：favicon 顺手换成小图

排查时发现 spec=0 那张 106.8KB 的图被请求了两次：一次是头像，一次是 favicon —— 而 favicon 在模板里直接复用了同一个 URL。浏览器对 favicon 的请求很积极，等于每来一个访客就白下 100KB。

改成 spec=140（6.2KB），缩到 16px / 32px 完全够用。

改动四：把 KaTeX 与 Prism 赶出全站关键 CSS

311.8KB 的关键 CSS 是这么来的：Layout.astro 里全局 import 了 katex.min.css、prism-tomorrow.css 和自定义的 prism-custom.css。可公式与代码块只出现在文章里，首页并不需要。

把这三个 import 从 Layout.astro 挪到 src/pages/posts/[...slug].astro，首页 CSS 从 311.8KB 降到 282KB，文章页依旧完整（多出 32.4KB 的 katex/prism chunk，按需加载）。

-// Layout.astro（全站）
-import "prismjs/themes/prism-tomorrow.css";
-import "katex/dist/katex.min.css";
-import "../styles/prism-custom.css";

+// src/pages/posts/[...slug].astro（只有文章页）
+import "katex/dist/katex.min.css";
+import "prismjs/themes/prism-tomorrow.css";
+import "../../styles/prism-custom.css";

效果

指标	改造前	改造后	变化
FCP	3708 / 7400 ms	2132 / 2772 ms	约快 3 倍
LCP	24080 / 43372 ms	2132 / 2772 ms	从「被横幅顶替」变成头像
长任务	10~13 个 / 1686~2121 ms	2~3 个 / 134~204 ms	主线程压力降一个数量级
头像 + favicon	215 KB	59 KB	少下 156KB
关键 CSS	311.8 KB	282 KB	少 30KB

第二轮：282 KB 里有 160 KB 是死代码

既然 CLS 卡在关键 CSS 上，下一步就是把它拆小。我写了个脚本按选择器前缀统计这 282 KB 的构成，结果很意外：

103.0 KB  (36.6%)  .toastui-editor-toolbar-
 32.9 KB  (11.7%)  .toastui-editor-context-
 15.8 KB  ( 5.6%)  .custom-md
 12.0 KB  ( 4.3%)  .prose

TOAST UI 编辑器的样式占了 160 多 KB，其中最夸张的一条规则：

.toastui-editor-toolbar-icons,
.toastui-editor-context-menu span:before { ... }   /* 71.9 KB */

那是把整套工具栏图标以 base64 内联成的雪碧图。问题是：这个站根本没有编辑器 —— 没有任何代码 import "@toast-ui/editor" 的 JS，也没有任何组件渲染 .toastui-editor-* 的 DOM。它只是上游模板留在 src/styles/main.css 开头的两个 @import：

-@import "@toast-ui/editor/dist/toastui-editor.css";
-@import "@toast-ui/editor/dist/theme/toastui-editor-dark.css";

删掉之后，首页关键 CSS 282 KB → 104 KB（−63%）。

顺手又处理了另一块：fancybox.css（32.4 KB）只有「点开文章图片」时才用得上，但 Layout 里那段脚本静态 import 了它，于是每个页面都吃一份。改成按需动态 import：

async function initFancybox() {
    if (!document.querySelector(".custom-md img, #post-cover img")) return;  // 没图片的页面直接返回
    const { bindFancybox, cleanupFancybox } = await import("@utils/fancybox");
    cleanupFancybox();
    bindFancybox(".custom-md img, #post-cover img");
}

现在 fancybox 的 JS 变成独立 chunk，只有文章页点图片时才下载（lightbox 行为实测未受影响）；它的 CSS 仍被 Astro 挂在共享 chunk 上，这块还没解决。

第三轮：CLS 的真凶是 DOM 顺序

砍掉 178 KB 之后 CLS 从 0.43 降到 0.29~0.39，但没根治。我一度以为继续砍 CSS 就行，直到把位移的坐标打印出来：

归档页：CLS 0.392，侧栏 y 78 → 564，位移 486px
主内容高度：486px

位移量 恰好等于主内容的高度 —— 这不是"字号变了导致的轻微抖动"，而是侧栏被整块推到主内容下面。

再去看 MainGridLayout.astro 的结构就明白了：

<!-- DOM 顺序：侧栏在前，主内容在后 -->
<div id="sidebar">…</div>
<main id="main-content">…</main>

但手机端网格用 row-start-1 / row-start-2 把主内容放到第一行、侧栏放到第二行：

<main id="main-content" class="row-start-1 …">
<div id="sidebar" class="row-start-2 …">

DOM 顺序与视觉顺序相反。样式还没生效（或晚到）时，浏览器只能按 DOM 顺序先把侧栏排在最上面；样式一到，网格把侧栏推到主内容下面 —— 486px 的整块位移就这么产生了。这也解释了为什么"关掉 JS 依然位移"：跟脚本无关，纯粹是排版兜底状态与最终状态不一致。

修法只有一件事：把 <div id="sidebar"> 整块移到 </main> 之后，让 DOM 顺序与视觉顺序对齐。桌面端的左右布局由显式 md:col-start-* / lg:col-start-* 决定，不受 DOM 顺序影响，所以一行都不用改。

改完实测：

页面	改前	改后
首页	0.394	0.000（0 次偏移）
归档页	0.392	0.000（0 次偏移）

最终成绩

指标	优化前	最终	Google「良好」线
FCP	3708 / 7400 ms	1364 / 1744 ms	< 1800 ms
LCP	24080 / 43372 ms	1644 / 1924 ms	< 2500 ms
CLS	0.50 / 0.70	0.000	< 0.1
长任务	10~13 个 / 1.7~2.1 s	1~2 个 / 53~117 ms	—
首页传输	392 KB / 76 请求	59 KB / 41 请求	—
关键 CSS	311.8 KB	104 KB	—

三项核心 Web Vitals 全部进入「良好」区间。回头看，几轮改动里收益最大的一条几乎没有技术含量：把侧栏从 <main> 前面挪到后面。

这也印证了排查 CLS 的正确姿势：先打印位移元素与位移量，再看那个数字能不能和某个元素的高度对上。对上了，八成是布局顺序/占位问题，而不是字体或图片。

小结

这次最值钱的不是那 4 个改动，而是测量脚本：同一套参数，改完再跑一遍，数字会诚实告诉你哪一步有效。

如果你也想量一次自己的站，记住三件事：

一定要同时降网速和降 CPU，只降一个会得出误导性结论；
记录每个请求的字节数和类型，比看总分有用得多；
盯住 LCP 元素是谁 —— 如果它是个 Cookie 横幅或侧栏卡片，说明真正的内容根本没排上队。

现在回头看，最贵的教训是那条 0.39 的 CLS：它逼着我先砍了 178KB 的 CSS（那 160KB 死代码确实该删），但真正修好它只花了一个 div 的位置调整。先量清楚，再动手。

缓存层是同一套思路的另一半：三层缓存各自为政里解释了为什么哈希资源要永久缓存；改样式踩的坑则记在 Astro 的三个隐形约定。

另外把「部署体积」和「访客成本」分开量了一遍：dist 16 MB，但首页压缩后只传 28 KB，见构建产物 16 MB，访客每次只下 28 KB。

博客 SEO 自我体检：27 个页面里揪出四个系统性毛病

Sat, 24 Oct 2026 08:45:00 GMT

站点上线三个月，Google 收录了首页和几篇文章，但长尾几乎没动静。与其在 Search Console 里猜，不如把构建产物当成一份可以逐行检查的试卷：我自己写了一支"体检笔"，一次性扫完 27 个页面，然后发现四个毛病全都不是个别页面写歪，而是模板层的系统性缺口。

[!NOTE] 环境：Astro 静态站（output: "static"），产物在 dist/，Node 22 + Python 3.13。体检脚本用 Python 写，只读 HTML、不依赖第三方库，跑一次不到两秒。

为什么不用现成工具

Lighthouse、PageSpeed Insights、SEO 检测站我全都试过，它们的问题不是不准，而是方向不对：

它们盯着单页打分，而模板问题会以"每页都掉一分"的形式出现，看不出共性；
它们检查的是普遍规则（有没有 viewport、有没有 HSTS），不关心"这个站的标题是不是一个 <div>"；
最要命的是依赖线上环境：本地改完还要等部署才能看到结果，来回十几分钟。

而我要回答的问题是：「我这套模板，每一页都合格吗？」这本质上是对构建产物做批处理，写脚本比点按钮快得多。

体检脚本：一张规则表 + 一次遍历

核心就是「读 HTML → 抽字段 → 套阈值 → 打印表格」。规则表是全文的灵魂，我列在下面，你可以按自己站的情况增删：

检查项	规则	为什么
`<title>`	存在，12~48 字	中文标题在 SERP 里大约展示 28~30 字，太长会被截断
`description`	存在，60~160 字，且各页不同	全站共用一段描述等于放弃摘要控制权
`canonical`	存在、绝对地址、指向自身	分页和标签页最容易写错
`<h1>`	恰好 1 个，且非空	0 个是丢了主标题语义，多个是主题分散
`og:image`	存在且可访问	分享到群里有没有缩略图全靠它
JSON-LD	存在且能被 `json.loads` 解析	结构错一个逗号就整段失效
`<html lang>`	存在	中文站最常见的一处遗漏
`<img alt>`	全部有	顺手查的无障碍项
正文字数	工具页/文章页 ≥ 300 字	抓"JS 渲染、爬虫看到空壳"的薄内容

代码不长，关键只有几行（完整版见文末）：

for page in sorted(DIST.rglob("*.html")):
    html = page.read_text(encoding="utf-8", errors="replace")
    html = re.sub(r"(?s)<!--.*?-->", " ", html)      # 注释里的 <title> 会骗过正则
    h1s = re.findall(r"(?is)<h1[^>]*>(.*?)</h1>", html)
    ...
    if len(h1s) != 1:
        issues.append(f"h1 数量 = {len(h1s)}")

[!TIP] 第二行是踩坑换来的：我一开始忘了剥注释，结果 404 页被判成「标题 330 字」—— 因为页面里有一句注释写着 <title>，正则一路吃到真正的 </title>。

第一次跑出来的结果

28 个页面，28 个"有问题"。把重复的行合并同类项，其实是四件事：

文章页 h1 = 0        → 9 篇文章 + 首页 + 分页页 + 归档页，一共 12 个页面
全站缺 og:image      → 28 / 28
静态页描述 = 34 字   → 8 个静态页 + 7 个工具页，全是站点默认描述
404 页 head 重复     → 两份 <head>、两个 <title>、两段描述

毛病一：文章标题根本不是 h1

打开文章页源码，标题长这样：

<div id="post-title" class="...text-3xl...">
    <span>博客 SEO 自我体检</span>
</div>

主题作者把标题当成"一段排版好的文字"来写，视觉上完全没问题 —— 字号、粗细、左侧那条主题色竖线都对。但语义上它只是一个 div，搜索引擎读到的文章页没有主标题。

修法是把 div 换成 h1，id 和 class 一个都不动：

-<div id="post-title" class="...">
+<h1 id="post-title" class="...">
     <span>{entry.data.title}</span>
-</div>
+</h1>

这里有个细节值得记：#post-title 被两个脚本按 id 依赖着（行内 diff 高亮、Pagefind 的搜索权重标记），所以只换标签、不换 id，改完这两处逻辑毫发无损。

首页、/2/、/archive/ 是另一类情况：它们本来就没有可见标题（只有文章卡片列表）。硬塞一个大标题会破坏设计，我的做法是给布局加一个 heading 属性，在 <main> 里输出一个 sr-only 的 h1：

{heading && <h1 class="sr-only">{heading}</h1>}

然后首页传「站点名 · 副标题」、分页页传「站点名 · 第 N 页」、归档页传「文章归档」。屏幕阅读器和爬虫都能读到，视觉上零变化。

毛病二：28 个页面都没有分享图

Layout.astro 里原本是这么写的：

{ogImage && <meta property="og:image" content={new URL(ogImage, Astro.site).toString()} />}

逻辑本身没错，问题在于文章 frontmatter 里普遍没有 image 字段 —— 于是 ogImage 永远是 undefined，这行永远不输出。分享到群里，卡片就是纯文字。

修法是给站点做一张默认图，然后无条件输出：

const resolvedOgImage = new URL(ogImage || "/og-default.png", Astro.site).toString();

这张图是用 Python + Pillow 画的（1200×630，竖版渐变 + 主题色光晕 + 微软雅黑），35 KB。只有用默认图时才补 og:image:width/height，文章自带封面时就不写死尺寸 —— 免得声明了 1200×630 实际是别的比例。

毛病三：十几个页面共用同一段描述

体检表里那些 34 特别扎眼：所有不传 description 的页面都落到了 siteConfig.description。对搜索引擎来说，这十几个页面的摘要是一模一样的 —— 摘要本该是"这一页讲什么"，不是"这个站讲什么"。

修法很土但有效：给每个页面单独写。14 个页面，全部控制在 60~72 字（中文的 SERP 摘要大约展示 78 字，60 是个安全值）：

<MainGridLayout
    title="工具"
    description="peroe 的博客在线工具箱：封面生成、图片画廊、幻影坦克、零宽短链等小工具，全部在浏览器本地运行，不上传数据、不需要登录。"
>

因为文件多，这类机械改动我用 Python 批量做，每处替换都断言「命中数 == 1」：

n = text.count(old)
assert n == 1, f"{rel}: 期望命中 1 处，实际 {n} 处"

没有这条断言，replace 静默不命中时你根本不会发现 —— 这项检查在本次改 23 处时救了我两次（有两处字符串写错了一个空格）。

毛病四：404 页输出了两份 head

体检表里 /404 那一行 description 是 34 字，可我明明给它写了描述。翻构建产物才发现页面里有两份 <head>：

<html><head>...<title>页面未找到 - peroe 的博客</title>
       <meta name="description" content="（站点默认描述）">
...<!----><html><head><title>页面不存在 - peroe 的博客</title>...

原因是 404 页这么写的：

<Layout title="页面未找到">          <!-- 外层已经套了一个 Layout -->
    <MainGridLayout title="页面不存在">  <!-- 这里面又包含一个 Layout -->

MainGridLayout 内部本身就包了 Layout，再套一层就成了「Layout 里套 Layout」——整份文档被渲染两遍，浏览器能容错，爬虫只会困惑。删掉外层那层就干净了。

[!WARNING] 这类错误不会报错、不会白屏，只有把产物当文本看才会暴露。所以体检脚本必须扫 dist/，而不是看浏览器里"页面能用"。

附带发现：薄内容工具页

体检表还标了两行字数：/tools/gallery/ 只有 105 字、/tools/files/ 只有 166 字。这两页的功能都是脚本渲染的（画廊靠 JS 拉图、文件列表靠 JS 渲染），爬虫来的时候看到一个空壳。

处理方式不是 noindex（这些页是有用的入口），而是补服务端渲染的正文：讲清楚这些图/文件从哪来、为什么不放第三方图床、下载前要注意什么。

复查：从 28 降到 12

剩下 12 条基本是"可以接受但能更好"的：工具页还没加 WebApplication 结构化数据、两篇演示文章的描述偏短、首页用的是站点描述（它本来就是站点首页，合理）。这类留在待办里，不再算问题。

顺手一提：站点地图曾经整整四天没被收录

体检顺带治好了另一个老毛病：Search Console 一直报「无法抓取」，而同一台服务器上的 rss.xml 却是「成功」。

真正的报错在详情页里（列表页只写"无法抓取"，点进去才看到「无法读取此站点地图」）。拿官方 sitemap.xsd 一校验，立刻现形：

Element 'changefreq': This element is not expected.
第一条 <url> 的子元素顺序: loc → priority → changefreq

官方 XSD 里 <url> 是 <xsd:sequence>，顺序必须固定为 loc → lastmod → changefreq → priority。我当初是按"看着顺眼"排的，XML 依然 well-formed，Bing 也照样认，只有严格按 XSD 校验的 Google 会拒收。

修完之后我在生成函数里加了一道自检：逐条 <url> 校验子元素顺序，不符就在构建日志里告警 —— 这种"静默失败"必须让构建期替人盯着。

一份可以照抄的体检清单

如果你也是静态站，把下面这张表对着自己的模板过一遍，八成能拣到几条：

每个页面恰好一个 h1，且 h1 不是 logo 也不是站点名（列表页例外，可以用 sr-only）；
og:image 一定要有兜底，别指望每篇文章都配封面；
描述逐页写，别全站共用 —— 这十几段文字是唯一能控制的摘要；
警惕嵌套布局：一个页面里出现两个 <title>，就是套了两层 Layout；
功能页要有服务端可见的正文，纯 JS 渲染的页面在爬虫眼里是空的；
XML 产物要按 schema 校验，well-formed ≠ 符合 XSD；
改完重新扫一遍，把"改好了"变成表格里的一个数字，而不是一句自我感觉。

小结

这四个毛病的共同点：它们都不影响"人能看见的页面"。h1 变成 div、描述复用、head 重复、正文靠 JS —— 浏览器里一切正常，所以永远等不到"有人报错"。

SEO 的日常因此更像定期体检而不是"修 bug"：写一支便宜的脚本、定一张规则表、每次改完模板跑一遍。这套流程两秒钟一次，比在站长后台等四天要划算得多。

体检脚本我已经放进了本地工具目录（seo-audit.py），下一轮维护时直接复跑；等文章攒多一些，再补 WebApplication、Article 的多语言字段和 sameAs 之类的细节。

体检里的性能部分单独写过一篇：首屏从 392KB 砍到 59KB。

把标签变成聚合页面的那次改造写在静态站的标签体系里。

这套体检的八项判据、九类真实问题与三条教训，后来单独整理成了一份可复跑的清单。

站内搜索是怎么做索引的，也单独写过：27 篇文章的站内搜索。

给静态博客的单篇文章上密码：构建期加密与浏览器解密

Mon, 05 Oct 2026 15:10:00 GMT

静态博客的每位读者拿到的都是同一份 HTML，「给某篇文章上密码」的第一反应往往是前端藏一下。真要让不知道密码的人读不到正文，只剩一条路：构建期就把正文加密成密文，密码只存在于作者的本地和读者的浏览器里。本站刚把这条路走通，过程中发现真正麻烦的不是加密，而是正文之外那些顺手搬运内容的地方。

[!NOTE] 前提：本站是 Astro 静态输出 + Svelte 组件岛，部署在 Cloudflare Workers 的静态资源模式下（assets.directory = ./dist，没有 Worker 脚本入口）。没有服务端逻辑、没有数据库、没有鉴权层——下面所有取舍都从这一点长出来。

没有服务端，「上密码」到底能不能做

能，但只能做一半，得先把期望摆正。

静态站构建完就是一堆文件，Workers 的静态资源模式只负责按 URL 发出去。读者 A 和读者 B 请求 /posts/foo/，拿到的是同一个字节流。既然服务端不做任何判断，任何「服务器校验密码」的方案在这里都不成立——没有地方运行那段校验代码。

剩下的只有两类：模板语法层面的掩护，和真加密。前者我全部排除了。

先排除三种障眼法

第一种是 CSS 隐藏：display: none、visibility: hidden、filter: blur(8px)。它们的共性是——正文完整地躺在 HTML 里：查看源代码、curl 一次、禁用 JavaScript，随便哪种都能读到。模糊是给眼睛看的，不是给解析器看的。

第二种是 JS 比对密码：密码写在脚本里，输入对了再 document.body.innerHTML = 明文。密码本身就在产物里，搜一下 password 就完了。

第三种本站现成就有：.spoiler，由 ||文字|| 语法（src/plugins/remark-spoiler.js）生成的 span：

newChildren.push({
	type: "html",
	value: '<span class="spoiler" title="点击显示">',
});

样式是给文字加一层毛玻璃，点一下才去掉：

.spoiler {
	filter: blur(0.4rem);
	transition: filter 0.3s;
	cursor: pointer;
	user-select: none;
}

它在防剧透这个场景里是对的：读者本来就想看，只是不想提前被剧透。当密码用就完全错了——文字从生成 HTML 那一刻起就是明文，Ctrl+U 就能读。

做法	正文在产物里的形态	谁能读到	适合挡什么
CSS 隐藏 / blur	明文	所有人（看源代码即可）	剧透、不想一眼看到的段落
JS 比对密码	明文 + 密码字符串	所有人（搜 `password` 即可）	什么都不适合
`.spoiler`（`\|\|文字\|\|`）	明文 + 一行 blur 样式	所有人	剧透、折叠长段落
构建期真加密	密文（盐 + IV + 密文）	只有知道密码的人	真正不想公开的内容

真加密的形态：三段数据流

思路的转变只有一句话：把「校验密码」换成「用密码解密」。密码不参与任何比较，它只是 PBKDF2 的输入；输错密码的唯一后果是 AES-GCM 认证失败、解出一堆乱码。所以产物里一个密码字符都没有。

本站的完整数据流是这样：

【构建期 · 本地，只跑一次】pnpm lock-post <slug>
  private/posts/<slug>.md            明文正文 + frontmatter 里的 password
    │ ① 临时写回 src/content/posts/<slug>.md（先去掉 password），跑一次全量构建
    │ ② 从 dist/posts/<slug>/index.html 抠出 .custom-md 的 innerHTML 与标题大纲
    │ ③ PBKDF2-SHA256(600000 次) 派生密钥 → AES-256-GCM 加密 { html, headings }
    │ ④ 写 src/data/encrypted/<slug>.json，把 md 换成 stub，删掉本轮含明文的 dist 页面
    ▼
  提交物只有两个：
    src/content/posts/<slug>.md        stub：frontmatter + encrypted: true，正文为空
    src/data/encrypted/<slug>.json     v / alg / kdf / iter / salt / iv / ct

【部署 · 交给 Cloudflare 构建】astro build --force
  dist/posts/<slug>/index.html         密码框 + 内联 JSON 载荷，没有正文

【浏览器 · 每个读者各跑一次】
  输入密码 → WebCrypto 按同一组参数派生密钥 → AES-GCM 解密
    → JSON.parse 出 { html, headings } → innerHTML 注入 → 重跑各项初始化

载荷的字段定义在 src/utils/encrypted-format.ts 里，这个文件刻意保持「浏览器安全」（不 import node:*），因为它同时被构建脚本和 Svelte 组件引用：

export interface EncryptedPostPayload {
	v: number;
	alg: string;
	kdf: string;
	iter: number;
	salt: string;
	iv: string;
	ct: string;
}

线上那篇演示文章的载荷长这样（ct 是 15 KB 级别的密文，这里截断）：

{
	"v": 1,
	"alg": "AES-GCM",
	"kdf": "PBKDF2-SHA256",
	"iter": 600000,
	"salt": "rjp/Yhf9CDBymyJmIBI8xw==",
	"iv": "w0oOgg1cN/5cHJDG",
	"ct": "o66vi+/pGH5NmLSJjzw7Cyhnc+XsAWuEXevAwcrVg9v1/0DwvtWvo+NbYT…"
}

盐、IV、迭代数都是公开的，这不是设计缺陷——密码学上它们本来就该公开，安全性由密码承担。真正要小心的是别让载荷提前闭合 HTML 标签：内联前过了一道转义，把 < 换成 \u003c（src/utils/encrypted-format.ts）：

export function serializePayloadForHtml(payload: EncryptedPostPayload): string {
	return JSON.stringify(payload).split("<").join("\\u003c");
}

另一个刻意的设计是载荷缺失时构建直接失败，不降级：src/utils/encrypted-payload.ts 找不到密文 JSON 就抛错，而不是安静地渲染成一篇空文章：

throw new Error(
	`[encrypted-post] 找不到加密载荷 ${ENCRYPTED_DIR}/${slug}.json；` +
		`请先在本地运行 \`pnpm lock-post ${slug}\` 生成密文（明文留在 private/posts/，不提交）。`,
);

对加密功能来说，「静默降级」比「构建失败」危险得多，所以这条错误信息故意写得很啰嗦。

参数与取舍

加密参数全部集中在 src/utils/encrypted-format.ts 顶部，注释里写明了来源（ShokaX 与 hexo-blog-encrypt v4 的交集）：

export const PBKDF2_ITERATIONS = 600000;
export const SALT_BYTES = 16;
export const IV_BYTES = 12;

参数	取值	为什么是这个值
KDF	PBKDF2-HMAC-SHA256	WebCrypto 原生支持，浏览器端不用引任何第三方密码库
迭代次数	600000	单次猜测的成本：每猜一个密码要算 60 万次 SHA-256
盐	16 字节随机	同一密码在不同文章里派生出不同密钥，彩虹表失效
IV	12 字节随机	GCM 的标准长度；同一密钥下 IV 重用是致命的，所以每篇重新生成
加密	AES-256-GCM，tagLength 128	自带认证标签：密码错和密文被改，都解不出来
版本与算法名	`v` / `alg` / `kdf` / `iter` 全部写进载荷	将来换参数时，已经发出去的密文仍能按自己的参数解开

为什么不用单次 MD5。 不少前端加密示例（比如 crypto-js 的默认用法 CryptoJS.AES.encrypt(text, password)）走 OpenSSL 的 EVP_BytesToKey：只做一次 MD5 派生密钥。单次 MD5 与 60 万次 PBKDF2-SHA256 之间隔着 60 万倍的计算量，GPU 再快，这个倍数也要照付——改加密参数不是「更安全一点」，是换了一个数量级。

为什么不用 bcrypt 先验密码。 bcrypt 回答的是「这个密码能不能通过校验」，而这里需要的是「用这个密码派生出一把能解密的密钥」——是 KDF，不是口令校验器。况且浏览器里没有原生 bcrypt，用一次就要引一个 wasm/JS 库，PBKDF2 则是 WebCrypto 自带的。iter 写进载荷也是同理：以后把 600000 调大，老密文不会被写坏。

浏览器端就是这两步：

const baseKey = await crypto.subtle.importKey(
	"raw",
	new TextEncoder().encode(passphrase),
	"PBKDF2",
	false,
	["deriveKey"],
);
return crypto.subtle.deriveKey(
	{ name: "PBKDF2", salt, iterations, hash: "SHA-256" },
	baseKey,
	{ name: "AES-GCM", length: 256 },
	false,
	["decrypt"],
);

安全边界，先把话说清楚

第一，密文、盐、IV、迭代数全在 HTML 里。攻击者不需要访问服务器，把页面存下来就能离线爆破，还能并行、不受限流影响。所以密码强度就是全部的安全性——600000 次迭代只能把弱密码从「一秒破」推迟到「几天破」，救不回来。

第二，出错提示必须统一。AES-GCM 下「密码错」和「密文被篡改」在客户端不可区分，硬要区分只会给攻击者送信息，所以本站只提示一种：

} catch {
	// 密码错误与密文被篡改在 AES-GCM 下无法区分，统一提示
	error = "密码错误";
	password = "";
}

第三，明文只在内存里。组件不写 localStorage 也不写 sessionStorage，代价是每次刷新都要重新解密（手机上大概一两秒）。把明文写进 localStorage，等于给密码保护留了一把备用钥匙。

第四，不算秘密的东西仍然公开：标题、URL、发布时间、文章存在性，以及 frontmatter 里的 passwordHint（它渲染成密码框下面那行小字，所以别把密码写进提示里）。

解密之后会发生什么（最容易翻车的地方）

解锁成功只是把 HTML 塞进 DOM，页面并不会重新加载一遍。而本站那些看着很时髦的渲染——代码高亮、图片灯箱、Mermaid 流程图、表格横向滚动容器、侧栏目录——都只在页面首次加载时跑一次，初始化挂在 DOMContentLoaded 上，解密却发生在页面早就 load 完之后。更隐蔽的是 innerHTML 注入的 <script> 根本不会执行，链接卡片 ::url{} 的元数据请求恰好写在脚本里。

所以 PasswordGate.svelte 里专门有一个「注入后重跑」的函数：

// innerHTML 注入的 <script> 不会执行（::url{} 链接卡片的元数据请求就在里面），手动补跑
bodyEl?.querySelectorAll("script").forEach((old) => {
	const script = document.createElement("script");
	for (const attr of Array.from(old.attributes)) {
		script.setAttribute(attr.name, attr.value);
	}
	script.text = old.text;
	old.replaceWith(script);
});

// 表格包裹 + Mermaid 渲染（逻辑在 components/misc/Markdown.astro）
window.dispatchEvent(new CustomEvent("fuwari:markdown-injected"));
// 代码高亮（Prism + 复制按钮）
initCodeHighlight();
// 图片灯箱（逻辑在 scripts/layout-fancybox-runtime.ts，避免把 Fancybox 打进文章页的 island 包）
window.dispatchEvent(new CustomEvent("fuwari:images-injected"));
// 侧栏目录（服务端渲染时 headings 被刻意传成 []）
window.dispatchEvent(
	new CustomEvent("fuwari:toc-rebuild", { detail: { headings } }),
);

三个事件各有接收方，都是「本来就在监听，只是以前没人派发」：

window.addEventListener("fuwari:markdown-injected", () => {
	initMarkdown();
});

window.addEventListener("fuwari:images-injected", () => {
	initFancybox();
});

侧栏目录特殊一点：服务端渲染时它是空的，因为标题大纲会泄露正文结构——

const encrypted = isEncrypted(entry);
const payload = encrypted ? getEncryptedPayload(entry.id) : null;
const tocHeadings = encrypted ? [] : headings;

所以密文里连 headings 一起加密了，解锁后由 fuwari:toc-rebuild 事件重建列表，还得把那个自定义元素重新初始化一遍（disconnectedCallback?.() 之后再 init?.()），否则目录只是「看起来在那里」但点不动。

这是整篇里最值得强调的一条经验：代码高亮和目录这类「增强」，写的时候都假设自己只跑一次。我第一次解锁时正文出来了，代码块却是白板、表格顶到卡片边缘、目录空着——功能全对，样式全烂。

公开仓库的坑：明文绝不能进 git

这是最容易做错、也最难补救的一环：本站文章页有一个「在 GitHub 上编辑此页」的直链，指向 src/content/posts/<slug>.md——那个文件必须能公开见人，而仓库本身也是 public 的。

所以本站把明文和提交物彻底分开：

文件	位置	是否提交	内容
明文 + 密码	`private/posts/<slug>.md`	❌（`.gitignore` 第 70 行忽略 `private/`）	完整正文，frontmatter 里带 `password`
stub	`src/content/posts/<slug>.md`	✅	frontmatter + `encrypted: true`，正文为空
密文载荷	`src/data/encrypted/<slug>.json`	✅	`v / alg / kdf / iter / salt / iv / ct`

本地的明文长这样（private/ 已在 .gitignore 里）：

# private/posts/<slug>.md —— 只在本地
---
title: 一条需要密码的私人笔记
published: 2026-10-05 23:50:00 +08:00
password: <你的密码>        # lock-post 读它；stub 里会被删掉
passwordHint: "……"        # 可选，会渲染成密码框下面那行提示
---
正文照常写 Markdown

一条命令完成整个转换：

pnpm lock-post demo-private-note

它按顺序做四件事，每一件都对应一个具体的坑：

读明文。从 private/posts/<slug>.md 读正文和 frontmatter 里的 password，缺失或正文为空就直接失败。
临时渲染 + 构建。把还原出来的 frontmatter（去掉 password）和正文写回 src/content/posts/<slug>.md，跑一次 pnpm update-diff + astro build --force，再从 dist/posts/<slug>/index.html 的 .custom-md 容器里抠出正文 HTML 和标题大纲。
加密 + 写载荷。crypto.getRandomValues 生成 16 字节盐和 12 字节 IV，PBKDF2 派生密钥，AES-GCM 加密 { html, headings }，写成 src/data/encrypted/<slug>.json。
换成 stub。把 src/content/posts/<slug>.md 覆盖成「frontmatter + 空正文」，顺手删掉本轮那个含明文的 dist 页面——因为「提取完忘了重建就部署」是最容易犯的错。

写完之后还有一道自检，把「密码泄漏进提交物」直接判死：

const leaks = [];
if (/^\s*password\s*:/m.test(stubText)) leaks.push("stub 里还有 password 字段");
if (stubText.includes(password)) leaks.push("stub 里出现了密码明文");
if (payloadText.includes(password)) leaks.push("密文 JSON 里出现了密码明文");
if (leaks.length) {
	fail(`自检不通过：${leaks.join("；")}`);
}

失败时怎么回滚。 这条命令会临时往被 git 跟踪的目录里写明文，所以脚本的 finally 块是无条件的：只要这一轮没走完，就一定把 src/content/posts/<slug>.md 恢复成 stub（或运行前的样子），绝不会把明文留在那里等你手动收拾：

} finally {
	// 无论成功失败，都不要把明文留在被 git 跟踪的 src/content/posts 里
	if (!completed && wroteTemp) {
		if (originalStub.includes(password) || /^\s*password\s*:/m.test(originalStub)) {
			fs.writeFileSync(tempFile, `---\n${stubFrontmatter}\n---\n`, "utf8");
		} else {
			fs.writeFileSync(tempFile, originalStub, "utf8");
		}
		console.error(
			`⚠️ 已把 ${path.relative(ROOT, tempFile)} 恢复为 stub（本轮未完成加密）`,
		);
	}
}

跑完之后，仓库边界可以用命令验证，不用靠自觉：

最后一条不在脚本里、在人的习惯里：提交信息也算公开信息。本站加密文章的提交信息只写标题（本来就公开），但如果你顺手把正文摘要写进 commit message，它就永久留在 git 历史里了。

元数据泄露清单：只加密正文远远不够

正文是最显眼的泄露点，却不是唯一的：静态站会在构建期把内容「搬运」到很多地方，我挨个查了一遍：

泄露点	会泄露什么	本站怎么处理
列表页摘要	`excerpt` 就是正文第一段（`remark-excerpt` 生成）	`PostCard.astro` 里改成固定文案 `🔒 需要密码`
字数 / 阅读时长	正文规模（几万字还是几百字，一眼看出）	包在 `{!encrypted && (…)}` 里，不渲染
侧栏目录 TOC	标题大纲＝文章结构	服务端传 `[]`，解锁后用密文里的 `headings` 重建
RSS 全文	`<description>` 里塞的是渲染后的正文 HTML	`rss.xml.ts` 里用 `publicPosts()` 过滤
`/search.json`	正文被压成纯文本的全文索引	`search.json.ts` 同样用 `publicPosts()` 过滤
`sitemap.xml`	给搜索引擎的入口	集合过滤条件里加 `data.encrypted !== true`
侧栏「总字数」	把加密文章算进去就等于公开它的长度	`Profile.astro` 累加时用 `publicPosts()`
上下篇标题	`prevTitle` / `nextTitle`	故意保留，见下
修订历史 / 编辑入口	commit message、diff、可点的源码直链	加密文章整块隐藏（`gitHubEditConfig.enable && !encrypted`）

过滤入口只有一个文件，src/utils/post-visibility.ts，其余地方一律调它：

/** 过滤掉加密文章（正文不可公开，不能进 RSS / 搜索索引 / 站点地图 / 字数统计） */
export function publicPosts(
	posts: CollectionEntry<"posts">[],
): CollectionEntry<"posts">[] {
	return posts.filter((post) => !isEncrypted(post));
}

列表页那一处是唯一需要「换个说法」而不是删掉的，因为卡片上总得显示点什么：

{ encrypted ? "🔒 需要密码" : (description || remarkPluginFrontmatter.excerpt) }

字数与阅读时长则直接隐藏：

{!encrypted && (
<div class="text-sm text-white/30 flex gap-4 transition">
    <div>{remarkPluginFrontmatter.words} 字</div>
    <div>|</div>
    <div>{remarkPluginFrontmatter.minutes} 分钟</div>
</div>
)}

站点地图是另一套过滤（它直接 getCollection，没走 getSortedPosts）：

// 加密文章不进站点地图（正文不对搜索引擎开放）
const posts = await getCollection("posts", ({ data }) => {
	return !data.draft && data.encrypted !== true;
});

故意保留的部分也要说清楚。 标题、URL、发布时间、文章存在性、上下篇标题，本站一概不隐藏。理由是读者需要在列表页看到「这里有一篇要密码的文章」，也需要能把链接发给别人；连存在性都藏起来的话，这套东西就变成「隐藏文章」了，那是另一个功能。取舍就一句话：加密保护的是正文，不是这篇文章的存在。

顺带一提，/posts.json 也没问题：它只有 /posts/<slug> 路径数组，没有正文或摘要。

去试一下演示文章

本站已经发布了一篇演示：《一条需要密码的私人笔记》，密码是 peroe-demo-2026，上面三张截图就是它的三个状态。建议按这个顺序试：

打开 /posts/demo-private-note/，看到的是密码框（图 1）。顺手 Ctrl+U 打开源代码，搜正文里的任何一句话——搜不到，页面里只有那段内联的 JSON 载荷。
随便输一个密码，等半秒左右，页面只多一行「密码错误」（图 2）。那半秒就是 60 万次 PBKDF2 在算。
输入 peroe-demo-2026，正文出现，公式、表格、提示框、代码块、链接卡片一起就位（图 3）。

什么内容适合加密，什么不适合

适合的是「不希望陌生人顺手读到，但也不是机密」的内容：只给一两个人看的私人笔记、账单与额度边界、还没定要不要公开的草稿、给朋友对答案的题解。

不适合的同样明确：

真正的秘密（API Key、口令、身份证号）不要放：别人可以离线爆破，读者也可能转发。
需要按人授权的内容不要放。这套方案只有一个密码，谁拿到都能看，没有账号体系。
需要撤回的内容要谨慎。密文一旦推出去就进了别人的缓存和 CDN；改密码重新加密只对新访客生效，已经存下旧 HTML 的人仍然能用旧密码解开。
纯防剧透内容没必要：.spoiler 那类轻量掩护就够了，真加密每次刷新都要解密，还要处理上面那一堆初始化。

这套方案的局限就三句：不含服务端鉴权（密码即全部）；不能防「读者自己转发解锁后的内容」；正文之外仍有一圈公开的元数据（标题、URL、存在性、发布时间）。接受这三条，它就能用。

小结

静态博客做密码保护，本质上是把「服务器校验」换成「密码学」：构建期加密、浏览器解密、产物里只有盐和密文。加密本身是半个下午的事，真正吃时间的是两件外围工作——把明文和密码挡在 git 之外，以及把构建期顺手搬运正文的角落一个个堵上；前者靠 private/ + stub + 自检 + finally 兜底，后者靠一个统一的 publicPosts() 过滤器。

如果你的博客也是纯静态、也有几篇不想公开的内容，这套方案可以直接照搬；但如果需要的是「按人授权、可撤回」，那就不是加密能解决的，得去要一个真正的服务端。

静态博客的站内搜索是怎么做的：一份 JSON 索引加自己写的打分

Mon, 05 Oct 2026 14:50:00 GMT

静态站没有后端，站内搜索这种「看起来必须有服务端」的功能就得换个思路。本站的办法很土：构建期把每篇文章压成纯文本塞进一份 search.json，打开搜索框时浏览器把整份索引拉下来，在本地逐字段数命中次数，再按日期排序。

这份索引现在 51,653 字节、6 条记录，最大的一条 14 KB。文章少的时候它很划算——零后端、零外部服务、零依赖；但代价也是真的：每敲一个字，整份索引重新下载一遍。这篇把这条链路拆开，讲清楚它为什么这么写、代价具体是多少。

[!NOTE] 前提：本站是 Astro 静态输出 + Svelte 组件岛，跑在 Cloudflare Workers 的静态资源模式上——没有服务端逻辑，也没有可写的数据库，所以「搜索」只能发生在浏览器里。下面的数字都是 2026-10-05 在 https://blog.juluo.work 上实测的，当时线上索引收录 6 篇文章。

先比较三条路

站内搜索常见三种做法，我挨个想过：

方案	为什么没用
Algolia / 各类托管搜索	要注册服务、拿 API Key、写前端 SDK，还要担心免费额度和数据出境。为了 6 篇文章不值得
Pagefind	构建期切片索引、运行时按需拉分片，是这类需求的正统解法；但本站文章总量还没到「一次全量下载会疼」的量级，引入它的配置成本大于收益
自己烘一份 JSON	构建期生成、前端全量加载、自己写匹配。没有任何外部依赖，索引随时可 `curl` 出来看一眼

我选了第三条。判断依据是一个很粗糙的估算：现在 6 篇文章的索引是 51,653 字节，平均一篇约 8.6 KB。按这个斜率，100 篇文章的索引约 860 KB，gzip 之后约 390 KB——到那个量级就必须换方案，但在 20 篇以内，全量索引的体验反而比按需加载更好（没有分片加载的延迟、没有索引构建服务）。

索引是构建期烘出来的

生成逻辑只有一个文件，32 行，src/pages/search.json.ts。Astro 会把这类 API 路由在构建时执行一次，把返回的 Response 落成静态文件 dist/search.json。

关键就是那个 toPlainText：把 Markdown 一条条削成单行纯文本（下面这段是原文，行尾注释是我为了说明加的）：

function toPlainText(markdown: string): string {
	return markdown
		.replace(/!\[[^\]]*]\([^)]*\)/g, " ")   // 图片语法整段丢掉
		.replace(/\[([^\]]+)]\([^)]*\)/g, "$1")  // 链接只留锚文本
		.replace(/```[\s\S]*?```/g, " ")         // 围栏代码块整段丢掉
		.replace(/`[^`]*`/g, " ")                // 行内代码也丢掉
		.replace(/<[^>]*>/g, " ")                // 残留的 HTML 标签
		.replace(/[#>*_\-~]/g, " ")              // Markdown 记号
		.replace(/\s+/g, " ")
		.trim();
}

这个函数决定了搜索能搜到什么、搜不到什么。 被它抹掉的内容不是小数——我拿本地 5 篇已上线文章（hello-world、security-headers-audit、ssllabs-https-grade、traceroute-packet-loss-misread、workers-free-tier-cost）实测过。口径先说清楚：统计的是去掉 frontmatter 之后的正文 Markdown、按 UTF-8 编码的字节数；行内代码按 toPlainText 自己的替换顺序数，也就是在围栏代码块被抹掉之后再数。

正文 Markdown 合计 60,863 字节
其中围栏代码块 4,036 字节（6.6%）、行内代码 5,472 字节（9.0%）、图片语法 4,258 字节（7.0%）
最后压出来的纯文本 45,391 字节，同时压掉了一部分体积

代价很明确：搜不到代码里的关键字。这不是推测——《Cloudflare Workers 免费额度够不够》那篇正文里写过 If-None-Match（在行内代码里），线上搜它是「无搜索结果」；我直接在索引文件里检索 Cache-Control（有两篇文章在行内代码里写过它），同样一个字都没有。取舍是我不想让索引被代码撑大——一篇技术文章的代码块往往比正文还长，全留下的话索引体积翻倍不止。

索引里到底装了什么

直接看线上那份文件的真实输出：

一条记录长这样（content 我手动截断了，其余是原文）：

[
  {
    "title": "关于本站",
    "description": "这是本站的第一篇文章：介绍一下这个博客是做什么的、用了什么技术，以及怎么联系我。",
    "content": "欢迎来到我的博客 👋 这里是我的个人空间，主要记录技术折腾、开发笔记和一些生活碎片。 这个站点 域名 ： 技术栈 ：Astro + Svelte + Tailwind CSS，部署在 Cloudflare Workers 上 …（此处截断）",
    "link": "hello-world",
    "published": "2026-10-05T00:00:00.000Z"
  }
]

只有 5 个字段，每一个都有理由：

title / description：直接来自 frontmatter，前端给它们最高权重
content：toPlainText 处理后的正文，占了整份索引 95.3% 的字节（49,237 / 51,653 字节）
link：post.id，也就是文章的 slug；前端拼成 /posts/<link>/ 当跳转地址
published：Date 被 JSON.stringify 序列化成 UTC ISO 串，前端用 new Date() 还原后排序。frontmatter 里写的 +08:00 在这里被换算掉了——文章里写 22:20，索引里就是 2026-10-05T14:20:00.000Z

没进去的东西同样是有意为之：tags（搜索里用不上，且会引入重复字符串）、封面图、HTML 渲染结果、目录结构。全部记录加起来 51,653 字节；用 curl -H "Accept-Encoding: gzip" 拉一次，过网 23,335 字节（本地 gzip -9 复算也是这个数），也就是约 23 KB——这是整站里唯一一个「为了某个功能专门下载的数据文件」，其余请求都是样式、脚本和页面本身。

[!NOTE] 「过网体积」有两个口径，别混着用。这里的 23,335 字节，是 curl 显式声明只要 gzip 时拿到的压缩体；后面「代价」一节里浏览器实测的 25,316 字节，是 Chrome 的 encodedBodySize——浏览器声明的是一整串编码（gzip, deflate, br, zstd），具体用哪一种由服务端按协商结果决定，同一行的 transferSize 还要再加上约 300 字节的响应头开销。差的这 1,981 字节不是谁算错了，是两份字节根本不是同一次压缩的结果；引用之前先想清楚说的是「我要 gzip 能拿到多少」还是「浏览器实际下了多少」。

前端：没有 Fuse.js，也没有模糊匹配

先把一件事说清楚：这套搜索不是模糊匹配，是大小写不敏感的子串精确匹配加权重打分。仓库里搜不到 fuse（git grep -i fuse 无命中，package.json 里也没有这个依赖），从计数、加权到截摘要、排序，全在手写的一个 searchPosts 函数里。

核心是「数命中次数」：

const hits = (
	fieldLower.match(
		new RegExp(keywordLower.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g"),
	) || []
).length;

if (hits > 0) {
	totalHits += hits;
	const typeScore =
		type === "title"
			? 10
			: type === "description"
				? 5
				: type === "link"
					? 3
					: 1;
	totalScore += hits * typeScore;
}

权重是这样定的：标题 10、简介 5、路径 3、正文 1，乘上命中次数累加成 score。关键词先做正则元字符转义再用 String.match 全局匹配，所以用户输入 [、* 这类字符不会炸正则。

到这里有个我在读代码时才发现的事实：score 算出来了，但没被用。 结果列表最后是按 published 排序的（默认最新优先，有个按钮切成最旧优先），界面上展示的是 hitCount（「命中 N 次」），score 只是被塞进结果对象里带了一路。也就是说打分的权重目前对搜索结果顺序毫无影响——它现在是个可以删掉的字段。我没动它，但这是个典型的「写的时候打算用来排序、后来改成按日期排就忘了删」。

另外两个细节：高亮是把关键词包成 <mark class="hl"> 后用 {@html} 注入的，main.css 里把 .search-panel mark 设成透明背景加主题色；摘要片段取命中位置前后各 40 个字符，两端补 ...，所以短关键词的上下文是够看的。

交互细节：中文输入法是最容易被忽略的那个

搜索框在顶栏，桌面端一个、手机端一个，都是 bind:value 双向绑定。真正花心思的地方在输入法：

<input placeholder="搜索" bind:value={keyword} on:focus={() => { void reopenPanelIfHasQuery(); }}
       on:input={sanitizeKeyword}
       on:compositionstart={() => { isComposingDesktop = true; }}
       on:compositionend={() => { isComposingDesktop = false; sanitizeKeyword(); }}

中文输入法在敲拼音的过程中会持续触发 input 事件。如果不拦，输入「zhongwen」时拼音中间态会被当成关键词查一轮，白白拉几次索引。所以组件用 compositionstart / compositionend 标记组合态，组合期间不触发搜索。sanitizeKeyword 则把关键词里的空白全删掉——实测输入 cloud flare，输入框里会变成 cloudflare，结果依然是 6 条。

面板里还有一排类型筛选（标题 / 简介 / 正文 / 路径），默认是单选，勾上「多选」可以组合。实测选「标题」后结果从 6 条降到 3 条，正好是标题里含 Cloudflare 的那三篇。输入 zzzznothing 时面板显示「无搜索结果」。

面板的开合不靠 Svelte 状态，而是直接操作 class：setClickOutsideToClose("search-panel", [...]) 在 document 上挂了点击监听，点到面板和三个搜索框以外的地方就加 float-panel-closed（CSS 里是 -translate-y-1 opacity-0 pointer-events-none）。实测点一下页面空白处，面板的 class 里立刻多出 float-panel-closed。

手机端的搜索框在展示上和桌面端不一样：#search-bar 在 430px 宽度下 display:none，用的是 #search-bar-mobile。顺带发现面板里那个 #search-bar-inside 输入框是死代码——它带着 hidden 类，在桌面和手机两种视口下实测都是 display:none，代码里只剩「点击外部时忽略它」这一处引用。这个我没清理，怕动布局出错。

还有一件我确实没做的事：没有快捷键。git grep keydown 在整个 src 下只有 fancybox 一处，搜索框没有 Ctrl+K、也没有 /。做静态博客的人很容易忘记「用户想搜的时候得先找到搜索框」，这个我记在待办里。

代价：每敲一个字都重下一次索引

这是整套方案里最实在的问题，我把它量化了：

在真实页面上用 350ms 间隔逐字敲 cloud（5 次 input 事件），/search.json 被请求了 5 次，累计下载 258,265 字节（decoded），过网 126,581 字节（encoded），单次耗时 84~101ms。关键词不变、只点一下类型筛选，请求数又从 5 变成 6。

原因在 fetchPosts 里这一行：

const response = await fetch("/search.json", { cache: "no-store" });

以及那个响应式块：keyword 或 selectedTypes 一变，就重新 fetchAndSearch。no-store 明确禁止浏览器缓存这份响应，所以每次都得走网络重新拿全量。有意思的是，服务端其实是支持条件请求的——带上 If-None-Match 再请求一次，返回的是 304，只要几百字节；而 cache: "no-store" 让浏览器根本没机会发这个条件请求。

同一份索引各取两次的对比更直观：默认缓存下浏览器本地已有副本，两次都只花 300 字节（走 304 复验）；no-store 下两次都是 25,616 字节全量。

[!TIP] 这就是这套实现里我准备先改的地方：去掉 no-store 或者把已经拿到的 allPosts 复用起来，两个改动都很小，能把「敲 5 个字符下 250 KB」压到几乎为零。写这篇的时候还是老样子，所以文章里的数字都是老的。

踩过的坑

1. 在 API 路由里写 Cache-Control 是没用的。 search.json.ts 里明明写的是 "Cache-Control": "public, max-age=600"，线上 curl -sI 拿到的是 public, max-age=0, must-revalidate + ETag。/posts.json、/rss.xml 三条一样，说明这是 Workers 静态资源层统一加的头——纯静态输出下，路由返回的响应头根本落不到文件上（这个话题在《我的博客响应头缺了什么》里写过一次）。想改的话，最省事的是 public/_headers（Workers 静态资源也支持这套规则），或者在 Worker 逻辑里自己改响应头；而仓库里目前没有 _headers 这个文件。

2. PowerShell 会把 ETag 的引号吃掉，导致误判「服务端不支持 304」。 我第一次测条件请求，用 curl.exe -H "If-None-Match: $etag" 发出去，请求头变成了不带引号的 If-None-Match: 5601094e…，服务端当然认为不匹配，返回 200 加完整内容。换成在 bash 里跑、引号保留，同一个 ETag 立刻返回 304——那个 288,727 字节的 CSS 也一样返回 304。顺带说一句：《Cloudflare Workers 免费额度够不够》里「带 ETag 重发没有 304」那条结论，多半就是吃了这个亏（当时测的是同一类请求）。测量脚本本身出错，比被测对象出错更常见。

3. results.sort() 原地排序把面板搞没了。 这一条不是我自己踩出来的，是主题上游的历史修复：提交 37dd9a3b 把 return results.sort(...) 改成了 return [...results].sort(...)，修的是「排序功能上线后第一次点排序按钮，面板消失」。这个提交的作者是主题原作者（二叉树树），不是本站主人。原地排序动的是同一个数组引用，上游没解释 Svelte 的响应式在这里具体怎么判定，我也没复现这个 bug，只能照着修法倒推原因。

4. 排序条件不能靠重新搜索。 点排序按钮如果重新走一遍 fetchAndSearch，就又要下载一次索引。现在的写法是把第一次的结果存进 allPosts，再用第二个响应式块只重算不重取。这也是前面那个「点筛选却多了一次请求」的来源——筛选条件变更走的是第一条路径。

5. Astro v6 升级后 entry.slug 变成 entry.id。 这一条同样是上游留下的历史，不是本站主人的功劳：索引里的 link 字段现在直接来自 post.id，而把 entry.slug 全部换成 entry.id 的是上游提交 a4332e21（作者同为主题原作者），那一次连带着 RSS、sitemap、卡片组件、search.json.ts 一起替换，不然文章链接会渲染成 undefined。这段经过我是从它的提交信息和 diff 里读出来的。

6. 索引的新鲜度等于部署的新鲜度。 我本地刚删掉一篇文章，线上索引里照样能搜到它，因为它是在上一次部署时烘进去的。静态索引没有「数据过期」这回事，只有「没重新部署」。

什么情况下继续用它

判断标准我给自己列了三条：

文章数在 50 篇以内、索引 gzip 后还在 300 KB 以下：继续用。零依赖、可 curl 验证、改一行代码就能调权重。
需要拼音搜索、错字容错、或者搜代码块里的内容：换方案。现在的实现是子串精确匹配，k8s 搜不到 Kubernetes，被 toPlainText 抹掉的代码块也永远搜不到。
文章超过 100 篇：必须换。按现在平均 8.6 KB/篇推算，100 篇的索引约 860 KB，no-store 下敲五个字符就是几 MB 流量，这对读者和免费额度都不友好。

近期我会按这个顺序改：先去掉 no-store 并把 allPosts 复用起来（省掉绝大部分重复下载），再把没用上的 score 删掉或者真正接进排序，最后才是考虑换掉整套方案。

一份 JSON 索引加一个手写的匹配函数，能撑多久取决于你写多少字——它现在撑得住，但它不是那种「可以放着不管」的实现：每加一篇文章，索引就大一点，而每次搜索都要把它整个搬一遍。

搜索索引和文章修订历史都依赖同一套内容集合，两者的构建期处理可以放在一起看。

给每篇文章加「更新记录」：用 git 提交历史自动生成文章修改时间线

Mon, 05 Oct 2026 14:35:00 GMT

「这篇文章是什么时候改的？」——这是我做博客时第一个没解决的问题。frontmatter 里的 updated 是我手填的：勤快的时候会更新，改个错别字的时候不会；而且读者没有任何办法验证它。最后我在文章页底部放了一块「更新记录」，列的是这篇文件在 git 里的真实提交，带日期、短哈希、提交信息，点哈希直接跳到 GitHub 的 commit 页。

下面是线上渲染出来的样子。但先别信它——图里那条提交跟截图里那篇文章毫无关系，第四节会讲清楚为什么。

[!NOTE] 站点环境：Astro 6 静态站，部署在 Cloudflare Worker 的静态资源模式，构建由 Workers Builds 从 GitHub 的 main 分支跑 pnpm update-diff && pnpm astro build --force。本文所有命令输出都是 2026-10-05 在本机真实执行的（Windows + Node v24.16.0 + git 2.53.0）。

一、为什么用 git 历史，而不是别的数据源

做「更新时间线」有三条路，我都想过：

手写 updated 字段。最省事，但它是自我声明，不是事实。我改一篇文章的时候经常只改正文忘了改字段，时间线立刻失真。

读文件系统 mtime。这个方案听起来很干净，实际完全不能用：CI 上克隆下来的文件，mtime 全是 checkout 那一刻的时间，跟文章的真实修改时间没有任何关系。本机看着正常、线上全是同一个时间戳，比不做还糟。

读 git 提交历史。时间、作者、说明、可点击的详情页，全都是现成的，零额外维护成本。代价是构建机上必须有完整的 git 历史——这正是第四节那个坑的来源。

我选了第三条。它多出来的成本只有一项：构建前要多跑一个脚本。

二、上半段：构建前把 git log 压成一个 JSON

链路起点是 scripts/update-diff.js，pnpm update-diff 就是跑它。它干的事情非常直白：遍历 src/content/posts 下的所有 .md / .mdx，对每个文件跑一次 git log。

const git = spawn('git', [
    'log',
    '--follow',
    '--pretty=format:%H|%ad|%s',
    '--date=iso',
    '--',
    filePath
]);

--follow 是必须的：文章改过 slug、挪过目录之后，不带这个参数历史会从改名那一刻断掉。

输出的每一行长这样：<完整哈希>|<ISO 日期>|<提交信息>。解析部分有个细节值得看一眼——注释里写着「message might contain |」：

const firstPipe = line.indexOf('|');
const secondPipe = line.indexOf('|', firstPipe + 1);

if (firstPipe === -1 || secondPipe === -1) return null;

const hash = line.substring(0, firstPipe);
const date = line.substring(firstPipe + 1, secondPipe);
const message = line.substring(secondPipe + 1);

它没有用 split('|')，而是手工定位前两个竖线再切三刀。这样即使提交信息里带竖线（我写提交信息时经常带表格或命令行片段），后面的内容也会原样落到 message 里，不会被截断。

文章一多，这里就是几十上百次子进程，所以脚本用了 spawn 而不是 exec，并且按 CPU 核数分块并发：

const MAX_CONCURRENCY = Math.max(1, os.cpus().length - 1); // Leave one core free

本机 16 核，所以运行时打印的是 Using concurrency: 15。这里刻意留一个核给主进程，避免脚本自己把机器占满。

还有一个设计我很喜欢——单篇失败不拖垮整体：

if (code !== 0) {
    console.warn(`Failed to retrieve git history for ${filePath}: ${error}`);
    resolve([]); // Resolve empty on error to keep going
    return;
}

git 命令非零退出、或者 spawn 本身报错，都只是 resolve([])。一篇文章查不到历史（比如刚 git add 还没提交），页面上少一块时间线而已，不该让整站构建挂掉。

最后，键名用的是文件相对 src/content/posts 的路径，并强制转成正斜杠：

const relativePath = path.relative(CONTENT_DIR, file).replace(/\\/g, '/');
const history = await getGitHistoryAsync(file);
historyMap[relativePath] = history;

这行 replace(/\\/g, '/') 是 Windows 上开发必须要的：不然本机生成 ssllabs-https-grade.md，Linux 构建机上生成 posts\ssllabs-https-grade.md，页面里查表全落空。

跑完之后产出 src/json/git-history.json：

这个文件是生成物，已经写进 .gitignore（仓库最后一行就是 src/json/git-history.json），不进版本控制，每台机器构建时现算。代价是构建顺序变成了硬约束：src/utils/git-history.ts 第 4 行是静态 import，

import gitHistory from "../json/git-history.json";

文件不存在时 Vite 直接在解析阶段报 Could not resolve "../json/git-history.json"。仓库的 docs/workers-deploy.md 专门为此写了一条：Build command 里的 pnpm update-diff 必须保留。我的看法是：让构建失败比让页面悄悄少一块好——所以这个「硬约束」我认。

每篇文章起一个 git 进程，文章数上去以后这一步会是构建里最先变慢的环节。我还没到那个量级，暂时按 cpus - 1 并发扛着，不提前优化。

三、下半段：页面按 slug 查表

文章页要拿历史，只有一行：

const history = getPostHistory(entry.id);
const lastUpdateTime =
	history[0]?.date || entry.data.updated || entry.data.published;

getPostHistory 做的事就是「补扩展名 + 查表」，但这个补扩展名是整条链路里最容易断的一环：

export function getPostHistory(postId: string): Commit[] {
	try {
		// Normalize ID to match keys in JSON (forward slashes)
		let normalizedId = postId.replace(/\\/g, "/");

		// Add .md extension if not present (entry.id doesn't include extension)
		if (!normalizedId.endsWith('.md') && !normalizedId.endsWith('.mdx')) {
			normalizedId += '.md';
		}

		// Look up in the pre-generated history map
		const historyMap = gitHistory as Record<string, Commit[]>;

		if (historyMap?.[normalizedId]) {
			return historyMap[normalizedId];
		}

		return [];
	} catch (e) {

JSON 的键是带扩展名的文件名，而 Astro 内容集合给的 entry.id 是不带扩展名的（ssllabs-https-grade）。两边靠这里补一个 .md 对齐——代码注释里也是这么写的。哪天换成别的 loader、或者文章改成 .mdx 以外的后缀，这里对不上，函数返回空数组，页面只是不渲染那一块，不抛错、不报警。这类静默退化是我后来加自检的原因。

渲染部分是普通的折叠块，但有几处体现了取舍：

{history.length > 0 && (
    <div id="revision-history" class="flex items-start gap-3 mt-4 scroll-mt-20">
        <div class="h-5 w-5 bg-[var(--primary)] flex items-center justify-center">
            <Icon name="material-symbols:history-rounded" class="text-[0.875rem] text-black/70"></Icon>
        </div>
        <div class="flex-1">
            <p class="text-white/80 text-sm mb-1">文章修订历史 ({history.length} 次)</p>
            <details class="group">
                <summary class="cursor-pointer text-sm text-[var(--primary)] font-medium hover:underline select-none">
                    查看变更记录
                </summary>
                <div class="mt-2 space-y-2 max-h-48 overflow-y-auto">
                    {history.map(commit => (
                        <div class="flex flex-col text-xs bg-white/5 p-2">
                            <div class="flex justify-between items-center mb-1">
                                <span class="font-bold text-white/70">{formatPostDateForDisplay(new Date(commit.date))}</span>
                                <a href={getCommitUrl(commit.hash)} target="_blank" class="text-[var(--primary)] hover:underline font-mono">
                                    {commit.hash.substring(0, 7)}
                                </a>
                            </div>
                            <p class="text-white/60 break-all">{commit.message}</p>
                        </div>
                    ))}
                </div>
            </details>
        </div>
    </div>
)}

几点说明：

默认折叠 + max-h-48 overflow-y-auto。改过几十次的文章不会把页面撑开，代价是读者必须多点一次才能看到内容。
history[0] 被当成「最后修改时间」。这里依赖 git log 默认的「新提交在前」，脚本没有额外排序，页面也没排。约定是靠 git 的默认行为撑着的，没有断言保护。
lastUpdateTime 的兜底顺序是「git 历史 → frontmatter 的 updated → published」。这个值会喂给 PostUpdateNotice，用来算「文章初次发布于 N 天前，最后修改于 M 天前」。所以 git 历史不只是装饰，它还参与页面上的时效性提示。
短哈希 + getCommitUrl：函数从 gitHubEditConfig.baseUrl（https://github.com/juluowork/fuwari/blob/main/src/content/posts）里截掉 /blob/ 之后的部分，拼成 /commit/<hash>。只要「编辑本文」那个配置是对的，commit 链接就自动对，不用配第二个地址。
一个我不太满意的耦合：整块（编辑入口 + 修订历史）被 {gitHubEditConfig.enable && (...)} 包着。也就是说关掉「在 GitHub 上编辑此页」，修订历史会一起消失。想只关编辑链接、保留历史，得先拆这层结构。我暂时留着——两个功能指向同一个仓库，一起开关也说得通。

四、浅克隆会把别人的提交按到你头上

上面这条链路在本机跑得好好的。但线上是错的。

写作时线上挂着 6 篇文章，我把它们的页面全抓了一遍。那 6 篇里有一篇当晚就被我删掉了（选题没价值），所以下表只列现在还挂着的 5 篇：

线上文章	显示的提交	显示的提交信息
`hello-world`	`64bbdda`	fix: 首篇文章发布时间补上 +08:00 时区，避免显示成次日
`security-headers-audit`	`64bbdda`	同上
`ssllabs-https-grade`	`64bbdda`	同上
`traceroute-packet-loss-misread`	`64bbdda`	同上
`workers-free-tier-cost`	`64bbdda`	同上

五篇文章，同一条提交。而这条提交在本地仓库里只动过一个文件——正是当晚被我删掉的那篇，跟上面这五篇一篇都不沾边：

$ git show --stat --oneline 64bbdda
64bbddad fix: 首篇文章发布时间补上 +08:00 时区，避免显示成次日
 src/content/posts/【已删除的那篇】.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

（上面那行文件名我换成了占位符：那篇已经不在仓库里了，git show 的原始输出是它的完整路径。）

换句话说：这五篇没有一篇是对的，全被贴了一条跟自己无关的提交。

原因不在脚本，在克隆深度。线上那次构建时，远端 main 的顶端就是 64bbdda，而构建机拿到的是一个浅克隆——整个克隆里只有那一个提交。在浅克隆里，唯一被 fetch 到的提交被当成根提交，而 git log -- <path> 对根提交的判定会退化成「这个路径存在于它的树里吗」。所有文章都在那棵树里，于是每篇文章都拿到了同一条提交。

我在本机复现了一遍：先 git clone --depth 1 建一个浅克隆，再往里补上两次父提交、把浅边界退到 64bbdda（也就是线上那次构建看到的顶端），然后 checkout 过去——这样克隆里依然只有一个提交，正好复现出线上那次构建的状态。

写作时本机这个完整克隆有 2359 个提交，--follow 只返回 f374f125 那条——那才是 SSL Labs 那篇真正的提交；浅克隆只有 1 个提交，同一个命令在两篇不同文章上返回了同一条 64bbdda。

这里有个容易误判的地方：浅克隆的症状不是「历史为空」，而是「所有文章共享同一条最新提交」。脚本对每条 git 命令只看退出码，浅克隆里 git log 退出码是 0、输出格式也完全合法，JSON 生成得漂漂亮亮，页面渲染得整整齐齐——错的只有内容。这种静默错误，只有把线上页面和本地 git log 对一遍才抓得出来。

顺带说明：现在每篇文章只有 1 条记录，不是因为功能坏了，而是站点刚建起来——我拿 git log --oneline --follow -- src/content/posts/<slug>.md 把当时仓库里现役的 5 篇文章挨个查了一遍，每篇都只有 1 条，就是各自的发布提交。历史要等后续修改才会变长。

（顺带一提，「每篇只被提交过一次」这话有个反例：当晚被我删掉的那篇，在历史里有两条改到文件内容的提交——一条发布、一条修正，而那条修正提交正是上面的 64bbdda；删掉它之后，历史里还多出一条删除记录。所以这个「一次」的统计口径只能限定在现役文章上。）

那为什么没配 fetch-depth: 0？因为现在没有地方配。构建跑在 Cloudflare Workers Builds 上，它的 Build settings 里能填的只有 Git 仓库 / 分支、Build command、Deploy command、Preview command、Root directory 和构建期环境变量，没有克隆深度这一项；同一页文档也明确说它不读 wrangler 配置里的 Custom Builds。actions/checkout 时代那种 with: fetch-depth: 0 在这里没处可写。

仓库里其实留着一条老路。停用的 .github/workflows/deploy.yml-nouse 里，构建步骤是这样的：

- name: Build
  run: git clone https://github.com/juluowork/fuwari temp && cd temp && pnpm update-diff && cd .. && mkdir -p src/json && mv -f temp/src/json/git-history.json src/json/git-history.json && rm -rf temp && pnpm build:cdn

它没有给 actions/checkout 传 fetch-depth，而是另外完整克隆了一份到 temp/、在里面跑 update-diff、再把 JSON 搬回来。不管当时作者是怎么想的，效果就是用一次全量克隆绕开浅检出。这条思路今天依然有效，只是执行位置从 Actions 挪到了 Build command 里。

我本机验证过的修法是先补历史再生成：

git fetch --unshallow && pnpm update-diff && pnpm astro build --force

在刚才那个 --depth 1 的克隆里跑 git fetch --unshallow，浅边界消失、历史整段补回来（提交数从 1 回到两千多；写作时本机 HEAD 是 2359 个提交），同一条 --follow 立刻返回正确结果；再跑 update-diff，生成的 JSON 里每篇文章都拿到了各自那条提交。

补完历史后，本地渲染出来的正确结果是这样的——还是第一张图那个页面，也就是《中间跳丢包 90% 需要管吗》那篇；哈希 b12e281，对应的提交是 b12e2810「posts:发布新文章《中间跳丢包 90% 需要管吗：一次 traceroute 误读的完整拆解》」，正是这篇文件自己的发布提交：

对比第一张图就能看出差别：数据链路一行没改，只换了克隆深度。

五、顺带做的行内 diff 编辑器

摸到「文章版本」这件事之后，我顺手加了一个只在调试时出现的功能：?__diff_debug=1 打开一篇文章，页面左下角会浮出一个面板。面板是单列上下排列的：标题、简介、正文三组字段各自「旧在上、新在下」——DiffDebugEditor.astro 里就是 oldArea 紧接着 newArea 两个 textarea，没有左右对照那一栏。点「保存并生成 DIFF」，差异会直接画在正文上——新增的段落套绿框，被删掉的段落划红线。

它的数据来源很有意思：旧内容来自 /rss.xml。DiffDebugEditor.astro 会 fetch 当前线上部署的 RSS，从 content:encoded 里取出渲染后的正文 HTML，存进 IndexedDB（fuwari-diff-debug-old）。也就是说，一个本来是给阅读器用的公开 XML，在这里被当成了「线上正文快照」的免费存储——不需要任何服务端接口、不需要额外部署。我实测过：写作时那次部署的 rss.xml 里，当时那 6 篇文章的完整正文都在，一共 101 KB（删掉一篇文章并重新部署之后，这个数会跟着变）。

生成完 diff 之后，结果写进 sessionStorage 的 fuwari-diff-debug-state，再派发一个 fuwari:diff-debug-updated 事件；src/scripts/post-inline-diff.ts 接住事件，把 diff 的每一行拿去和正文里的 p / li / blockquote / pre / h1~h6 做文本比对，找到对应节点再加 class。

取舍要老实讲：

匹配是按文本，不是按源码行。我改了措辞、动了标点，旧行在正文里找不到，就只能退化成一整行红色的「已删除」块插在上下文旁边。图里效果好看，前提是「新旧文本大部分能对上」。
全局只插一个 #post-diff 锚点，多个改动块共用它，所以它只能告诉你「这里变了」，没有 GitHub 那种逐块跳转。
成本落在所有读者身上。面板要带参数才显示，但它的脚本是文章页的固定模块。我从线上抓了一下：DiffDebugEditor...js 是 12.5 KB（brotli 传输 4.8 KB），文章页 6 个 JS 模块的 brotli 传输量加起来 34.2 KB——也就是约 14% 的文章页 JS 预算，花在一个绝大多数读者永远不会打开的面板上。
还有一个没做完的地方：post-inline-diff.ts 里 applyInlineTextDiff 和 tryApplyInlineReplace 两个函数直接 return false，全文件也没有任何地方调用它们。字符级的行内 diff（只把改动的那几个字标红）留了位置但没实现，现在是块级效果。

我暂时选择留着这个功能：4.8 KB 换「改完稿立刻看到差异」，对一个月更几篇的个人博客是划算的。但如果哪天文章页 JS 预算变成硬约束，第一个该砍的就是它——把面板改成 ?__diff_debug=1 时再动态 import() 即可，不需要动数据结构。

六、如果你也要做，按这个清单来

数据源选 git，前提是克隆深度。git log --follow 是性价比最高的「更新时间线」数据源，但它在构建机上能不能用，取决于克隆深度——这是唯一的前提，也是唯一会静默失败的地方。
浅克隆的症状是「所有文章共享同一条最新提交」，不是「历史为空」。看到这个特征基本可以确诊；git fetch --unshallow 是验证和修复都最快的一步。
生成物就别进仓库。git-history.json 放 .gitignore，让构建前现算；同时接受「构建必须先跑脚本」这个硬约束——静态 import 的报错很明确，比页面悄悄少一块好得多。
给键名约定加一道自检。我这套是「相对路径 + .md」，对不上时函数返回 []、页面静默不渲染。我打算在 update-diff.js 结尾加一个检查：如果多篇文章拿到同一个哈希、而那篇文章只有一条记录，就让脚本以非零码退出。
调试功能要算进所有读者的预算。能用 URL 参数触发的 UI，不代表它的代码不用下载。上线前抓一次产物里的 chunk 大小，心里有数再决定留不留。

如果更关心内容侧怎么变成可检索的产物，站内搜索那篇讲了索引是怎么切出来的。

Workers 免费额度够不够：算一笔真实账

Mon, 05 Oct 2026 14:20:00 GMT

「Cloudflare Workers 免费套餐每天 10 万次请求」——这句话几乎每篇介绍 Cloudflare 的文章都会写一遍。但它对一个静态博客来说几乎是无效信息：静态资源请求压根不参与这个计数。

真正决定你能撑多少 PV 的，不是总请求数，而是每次访问里有多少请求会落到 Worker 脚本上。这篇文章不搬文档，只做两件事：把免费额度的口径拆清楚，然后用我自己博客的实测数据算一遍。

[!NOTE] 前提：本站是 Astro 静态站，部署在 Cloudflare Worker peroe-blog（纯静态资源模式，wrangler.jsonc 里只有 assets.directory 和自定义域，没有 main、没有 run_worker_first），Cloudflare 免费套餐，没买 Argo 或 Pro。账号下还跑着另外两个 Worker：cf-umami（t.juluo.work，浏览量统计 + D1）和 link-card（icon.juluo.work）。本文所有数字来自公开计费规则 + 本机实测，我没有登录 Cloudflare 后台看计量数据（那需要账号权限，也看不到历史曲线）。

免费额度的口径：三个数字，只有一个跟静态站有关

先看官方定价页给免费套餐列的三项：

表格下面那几个小脚注才是真正的规则，比表格本身重要得多：

脚注 3：Requests to static assets are free and unlimited. —— 静态资源请求免费且不限量。
脚注 1：Cloudflare 不为你 Worker 发出的子请求（subrequests）计费。
定价页开头还有一句：Workers 不额外收流量（egress）和带宽（throughput）费用。

也就是说，「每天 10 万次」这个额度只对会调用到 Worker 脚本的入站请求生效。对纯静态站来说：HTML、CSS、JS、图片、甚至自定义 404 页面，全部走静态资源路径，一次都不计。

Static Assets 自己的 Billing 页把这条讲得更直白：

请求要么命中静态资源、要么调用 Worker 脚本，只有后者按 Workers 定价计费；连「存储资产」都不额外收钱。另外还有两条跟套餐无关的平台限制要注意：每个 Worker 版本最多 20000 个文件、单文件最大 25 MiB——把图片全塞进仓库的话，这两条会比请求数更早成为约束。

还有一点常被忽略：10 万/天是账号级额度，不是每个 Worker 分一份。我账号下三个 Worker 共用同一个池子。

[!WARNING] 这里有个容易翻车的例外：一旦用了 run_worker_first（让 Worker 脚本优先处理请求），匹配到的请求就一定会进脚本、一定计费；免费额度用完之后，这些请求直接返回 429 Too Many Requests，不会退回静态资源。所以「静态站随便跑」成立的前提，是你的配置里没有 run_worker_first。

我的站一次访问产生多少请求

口径清楚了，接下来是数数。我用 Chrome + Playwright 记录冷缓存加载过程中的全部网络请求（每次都用全新的浏览器 profile，避免本地缓存干扰），分别测了首页和一篇带评论区的文章页：

指标	首页	文章页
总请求数	62	90
发往 blog.juluo.work	29	32
发往 t.juluo.work（自建统计）	1	1
传输体积	1153.7 KB	1513.9 KB

拆开看：

发往自己站点的 29 个请求里，没有一个是 Worker 脚本调用：1 个 HTML、2 个 CSS、18 个 JS，其余是页面加载后 astro:prefetch 预取的链接请求（RSS、归档、友链、站点地图这些）。它们全部命中静态资源，按上面的规则不计费，带宽也不计费。
真正计费的只有 1 个请求：POST https://t.juluo.work/batch。这是主题自带的浏览量排序脚本，首页和文章页各调一次，用来一次性拉回全站和各篇文章的阅读数。
剩下的一大半请求发去了别人家的域名：首页 32 个、文章页 57 个。图标走 api.iconify.design（一次首页 22 个、文章页 28 个 SVG，全站最「话痨」的一环），评论区走 giscus.app（文章页 17 个请求），统计走 cloud.umami.is，还有 QQ 头像、Cookie 同意横幅、浏览器升级提示。这些跟我的额度无关——花的是别人家的钱。

所以对我这个站来说，结论很干净：一次浏览 = 1 个 Workers 请求。

那 10 万/天能撑多少 PV

一个除法：100000 ÷ 1 = 100000 PV/天，约每月 300 万 PV。

这个量级对个人博客是什么概念？本站上线到现在，自建统计里的浏览量还是 0（下一节会讲为什么）。哪怕按「一天一千 PV」这种对个人博客已经算热闹的量来算，也只用到额度的 1%。

但这里有个更重要的推论：先撞墙的不是博客本体，是统计服务。博客本体跑在静态资源模式上，理论上请求数无限；而 t.juluo.work 每被浏览一次就消耗一个额度。真到额度见底那天，博客还能照常打开，只是浏览量数字不动了——这其实是个挺健康的失效模式。

再往后才是 D1 的账。D1 免费套餐是「每天 500 万行读、10 万行写、5 GB 存储」，跟 Workers 请求数是两套独立池子。如果 POST /send 每次写入 1 行，那 10 万行写/天对应的正好也是 10 万 PV/天，两块额度会一起见底。真正需要盯的是行读：官方对「行读」的定义是「查询扫描了多少行」，全表扫描时表里有多少行就算多少行。如果 /batch 随着文章变多退化成扫描，表越大、每次浏览消耗的行读越多，天花板就会从 10 万 PV 一路往下掉。这一条我在外部看不到计量数字（要登录后台看 D1 的 Row Metrics），所以只能当提醒，不当结论。

什么情况下会撞墙

把「什么时候免费额度不够用」列成一张判断表，比背数字有用：

你往站里加了什么	每 PV 计费请求	理论上限
现在这样（纯静态 + 统计 `/batch`）	1	10 万 PV/天
真正接上 `tracker.js` 上报（每 PV 多 1 次 `POST /send`）	2	5 万 PV/天
再加上 `tracker.js` 不吃缓存（`/send` + `tracker.js`）	3	3.3 万 PV/天
开 `run_worker_first`，静态请求也进脚本	+30 左右	3 千 PV/天
加 SSR 页面 / 实时接口	每个动态请求 1 个	看动态请求占比

最后两行是重点：静态站之所以「不花钱」，不是因为请求少，而是因为请求走对了路径。一旦引入 SSR、搜索接口、点赞、动态 OG 图这类东西，数字会立刻变得敏感。

另外两个限制跟容量无关，但会先把你卡住，值得单独记住：

CPU 时间 10 毫秒/次调用。注意 CPU 时间只算真正在跑的代码，等 D1、等上游 fetch 的 I/O 等待不算——所以「查一次数据库」通常不等于「烧掉 CPU」。真正吃 CPU 的是密码学运算、大 JSON 序列化、图片处理这一类。
超限之后的行为，官方在限制页写得很清楚：

免费套餐的 10 万/天按 UTC 零点重置，超出后返回 Error 1027；路由配成 Fail open 会绕过 Worker（当作没配 Worker 处理），Fail closed 则直接返回 1027 错误页。对静态站来说这是好消息：静态资源那条路根本不经过这个判断。

我踩到的坑

1. 统计接口返回的全是 0

我用 curl 直接问自建统计服务：

# 单个路径查询
curl -s "https://t.juluo.work/share?pathname=/"

# 批量查询（正文是裸数组，不是对象）
curl -s -X POST "https://t.juluo.work/batch" \
  -H "Content-Type: application/json" \
  --data-binary '["/","/archive/"]'

GET /share?pathname=/ 返回 {"pathname":"/","views":0}，POST /batch 返回 [0,0]，换七八个路径全都是 0。一开始我以为 D1 挂了，查下来是另一回事：接口是好的，只是没人往里写。站点前台引的是 Umami Cloud 的 script.js，自建的 tracker.js 没有被任何页面引用——这套自建统计目前「只有读、没有写」，读接口还跑得挺勤。

[!TIP] 踩这个坑的时候顺手发现：/batch 的请求体是裸 JSON 数组（["/","/archive/"]），不是 {"pathnames":[...]}。用对象去请求会返回 {"ok":false,"error":"expected_array"}——错误码其实直说了要数组，但如果你像我一样先写成 {"pathnames":[...]}，还是得愣一下才反应过来。

这个坑跟计费直接相关，也是我最想吐槽的一点：我现在每次浏览都在白花一个请求额度——首页那个 /batch 吭哧读半天，读出来全是 0。修法很简单（把 tracker.js 引到 Layout 里），但我打算先留着：一是现在没什么读者不值得上报，二是想先观察 D1 行读的增长曲线，等有真实流量了再接。

2. 用 `curl -I` 探活会误判

curl -I https://t.juluo.work/tracker.js（HEAD 请求）返回 404，而换成 curl -s -D - -o NUL（GET）返回 200。这个 Worker 只处理 GET，HEAD 直接落到 404 分支。我差点据此判断「tracker.js 不存在」，实际上它好好地在那儿：Content-Length: 801、Cache-Control: public, max-age=3600。探活请用 GET。

3. 282 KB 的 CSS 每次都会重发一遍

/_astro/MainGridLayout.*.css 有 288727 字节（282 KB），响应头是 Cache-Control: public, max-age=0, must-revalidate。我拿着 ETag 用 If-None-Match 再请求一次，返回的仍然是 200 OK + 完整的 288727 字节，没有 304。

从计费角度看这无所谓——静态请求和带宽都免费，多传几次 Cloudflare 也不会多收一分钱。但对国内读者来说，每次站内跳转都要重新拉一遍 282 KB 的 CSS，体验损耗是实打实的。真要优化，方向是给 _astro/* 加长缓存（Assets 支持 _headers 文件），而不是去省请求数——在免费额度这件事上，带宽和静态请求是最不该被优化的东西。

小结

「每天 10 万次请求」这个口径对静态站基本无效：静态资源请求免费且不限量，带宽也不计费。要数的只有落到 Worker 脚本上的请求。
实测本站：首页 62 个请求、文章页 90 个，其中计费的都只有 1 个（自建统计的 /batch）。理论上限 10 万 PV/天，而且先见底的是统计服务，不是博客本体。
判断自己的站会不会撞墙，一个式子就够：PV 上限 ≈ 100000 ÷ 每 PV 落到 Worker 的请求数，分子还要被账号下其它 Worker 分掉。
最容易翻车的不是流量涨了，而是你往静态站里塞了动态的东西：run_worker_first、SSR、实时接口。摸清请求路径，比记住额度数字有用得多。
免费额度之外，先卡住我的更可能是「每个版本 2 万个文件」和「单文件 25 MiB」这两条静态资源平台限制——这一点等配图多起来再单独验证。

额度之外，另一个常被低谷的成本是流量：三层缓存里把哈希资源改成永久缓存，就是为了少发请求。

静态博客怎么显示每篇文章的浏览量：从 D1 读数接口到前端排序的完整链路

Mon, 05 Oct 2026 14:15:00 GMT

静态博客最难的不是写页面，是页面之外的数字：每篇文章有多少人看过、全站累计多少。这些数字不在文件系统里，也不在构建产物里——你得先有东西把它写进某个地方，再把它读回来。

我这套的分工是：访客画像交给 Umami Cloud 的官方脚本（有后台、有地域和设备维度），页面计数用自己写的一套接口（t.juluo.work + D1 里一张两列的表）——页面引 tracker.js 往 /send 报一次，卡片再把 /batch 读回来渲染。本文按数据流讲一遍：从那两列的表，到文章页 meta 行里的「N 次」，再到列表页点一下眼睛图标就按热度重排。代码都在这个仓库里，接口行为全部用本机 curl 和 Chrome 实测过。

[!NOTE] 两处后记，都是同一晚发生的事：写入端（tracker.js）原本忘了接，见第一篇补记；数据源后来改成优先读 Umami、自建退成兜底，见第二篇补记。正文里过时的说法我都标了「改造前」。

[!NOTE] 前置：本站是 Astro 静态站，跑在 Cloudflare Worker 的静态资源模式上（没有 main、没有服务端逻辑，构建产物直接由边缘节点分发），域名 blog.juluo.work；计数接口是另一个 Worker cf-umami（源码在公开仓库 juluowork/cf-umami），数据存在 D1 的 pageviews 表。展示侧的开关就两个字段，写在 src/config.ts 里：

// 文章/页面浏览量：自建统计服务（Cloudflare Worker + D1，部署在 t.juluo.work）
export const viewCounterConfig: ViewCounterConfig = {
	enable: true,
	endpoint: "https://t.juluo.work",
};

先看这套东西现在的样子

文章页的标题下面那行 meta：发布时间、浏览量图标加一个「0 次」。这个数字不是构建时写死的——看组件模板就知道（下面贴的是 PostMeta.astro 的源码，不是渲染后的 HTML），它渲染出来就是个空壳，slug 是文章 id：

<div class="flex items-center" id={`page-views-wrapper-${slug}`} style="display: none;">
    <div class="meta-icon">
        <Icon name="material-symbols:visibility-outline-rounded" class="text-xl"></Icon>
    </div>
    <span class="text-50 text-sm font-medium" id={`page-views-${slug}`}></span>
</div>

首页同样，每张卡片下挂着一个「0 次」，右上角多了排序控件。顺便注意侧栏：首页有「访问量 0」，文章页没有——这不是设计，是实现细节，放在「踩坑」里说（后来修掉了，见文末补记）。

真正值得在意的不是那一刻的 0，而是为什么会是 0：读数接口一路通着（下面有实测），却没有任何页面在往计数表里写。本文写作时（2026-10-05 晚）这套系统处于「只读不写」的状态，这个坑当天深夜补上了，改动集中在文末补记里；正文保留的代码与截图是当时的样子，我会在对应位置标出哪些已经变了。

为什么不用第三方统计的 API

最省事的做法是前端直接去第三方统计的分享页拉数字。我没选，理由都跟「展示」这个场景的特殊性有关：

分享页是给人看的页面，不是给浏览器 fetch 的接口。 它属于统计后台的一部分，渲染方式随时可能变，而文章卡片要长期依赖它的响应结构——绑得越紧越难拆。
跨域和配额都不在我手里。 读数请求要从 blog.juluo.work 打到别人的域上，失败时我连「为什么失败」都看不到——是 CORS、是限流，还是接口改了。
展示只需要一个整数。 来源、设备、停留时长这些留在统计后台看就好，为了一个数字去拉一个通用分析接口，是拿大炮打蚊子。

自建的代价也很实在：多一个 Worker、多一张表、多一处要维护的东西。但它的失效模式是干净的：接口挂了，博客照常打开，只是数字不显示（我实测过，见后面的失败兜底）。

[!NOTE] 这段写于当晚 22 点，两个多小时后我自己把它推翻了：展示的数字改成优先读 Umami 的分享接口，自建那份退成兜底。三条理由本身没被推翻——变的是多了兜底，所以可以冒「接口随时会变」这个险。具体见文末「再补一刀」。

数据表：只有两列，是刻意的

D1 里的建表语句就一行（来自 cf-umami 仓库的 src/index.ts，我用 curl 核对过部署版本返回的错误字符串，行为与它一致）：

CREATE TABLE IF NOT EXISTS pageviews (pathname TEXT PRIMARY KEY, views INTEGER NOT NULL);

写入也只有一句 UPSERT：

INSERT INTO pageviews(pathname, views) VALUES(?, 1) ON CONFLICT(pathname) DO UPDATE SET views = views + 1;

pathname 直接当主键，views 就是个整数计数。没有 IP、没有 UA、没有 session、没有时间戳。 这不是偷懒，是取舍：

好处：表小，查询就是一次主键查，不存任何可识别信息，连「匿名化」这一步都省了。
代价：UV、来源、停留时长、趋势曲线一概没有，这些交给 Umami。

另一个直接后果是路径必须规范化。同一个页面只要能通过两个 URL 打开，计数就会裂成两条。我的文章页只有 /posts/<slug>/ 一种形态，工具页统一用组件里写死的 pathname（比如 /tools/cover/ 这个页面，实际读写的路径是 /cover/——实测抓到的请求就是 GET /share?pathname=%2Fcover%2F），所以这件事暂时没炸。

接口契约：两个读接口，一个写接口

三个端点用 curl 跑一遍，下面是线上真实响应：

GET /share?pathname=/posts/xxx/ → {"pathname":"/posts/xxx/","views":0}，单个页面读数；参数缺失返回 {"ok":false,"error":"invalid_pathname"}。
POST /batch，请求体是裸 JSON 数组 ["/","/posts/xxx/"]，返回同序数组 [0,0]；传对象进去会被拒：{"ok":false,"error":"expected_array"}（HTTP 400）。
POST /send，单个写入，请求体是 {"pathname":"/"}，只接受来自本站 Origin/Referer 的请求，其他来源直接 HTTP 204 静默丢弃。

[!WARNING] Windows PowerShell 会把命令行里内联 JSON 的双引号吃掉。--data-raw '["/"]' 实际只发出了 3 个字节，接口回 {"ok":false,"error":"invalid_json"}；把请求体写进文件、用 --data-binary "@file" 才能正常测通。我第一次测 /batch 就被它坑了，差点以为接口不认数组。

为什么读数用 POST 而不是 GET。 语义洁癖会说「读操作该用 GET」，但这套接口要一次读 N 个路径：GET 只能靠 ?pathname=a&pathname=b 或者逗号分隔，URL 长度、编码、去重规则全得自己定；POST + JSON 数组能把「顺序」表达得最清楚——顺序就是契约，讲排序时你会看到它有多关键。副作用是 POST 天然不可缓存，每次浏览都真的打一次查询，好处是数字永远新鲜。

前端：一次批量读，先藏后显

上图是单页读数组件 src/components/ViewsCounter.astro，用在工具页、课程表这类没有文章卡的页面上：/share 读一个路径、写进 span、把 wrapper 从 display: none 改成 flex。

关键在「藏」这个动作上。 组件渲染出来的 wrapper 带 style="display: none;"，服务端渲染阶段它就是个不占位的空壳，数字是客户端拿到之后才亮的。如果先渲染一个「0 次」占位、等接口回来再换成「1234 次」，用户会看到数字跳变，数字宽度变化还会把整行 meta 往前推一下——比晚半秒出现难看得多。代价是这一行从无到有时，下面的内容会有一次小位移，但至少不会有错误的数字被看到。

实测：工具页整页只发出 1 个请求 GET /share?pathname=%2Fcover%2F，然后 span 里出现「0 次」。

文章页和列表页走的是另一条路——批量读。一页最多 8 张卡片（src/constants/constants.ts 里的 PAGE_SIZE = 8），每张各发一个 /share 就是 8 个请求，既慢又费额度。所以这里的机制是「先登记、再一次性取数」——不是并发发起 N 个请求，而是把 N 个路径压进同一个请求：

登记这一步做在卡片组件里（src/components/PostMeta.astro 的内联脚本，页面上有几张卡片就有几份）：

window.__VIEWS_QUEUE__ = window.__VIEWS_QUEUE__ || [];
if (!window.__VIEWS_QUEUE__.includes(slug)) {
    window.__VIEWS_QUEUE__.push(slug);
}

真正发请求的是独立的读取端 src/scripts/view-counter-runtime.ts（挂在 Layout.astro 上，所以每个页面都有，而且每页只跑一次）：

const slugs = collectSlugs(); // 列表页读 __PAGE_POSTS_DATA__，其它页面读 __VIEWS_QUEUE__
const pathnames = ["/", ...slugs.map((slug) => `/posts/${slug}/`)];
const res = await fetch(`${endpoint}/batch`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(pathnames),
});

请求体永远以 / 打头，所以不管在哪一页，侧栏那个全站访问量都能顺带取回来。抓包实测：线上首页是 9 条路径（/ 加 8 篇文章），发往 t.juluo.work 的请求只有 1 条——POST /batch。代价也在这句话里：只要其中任意一个 pathname 不合法，整个 /batch 就返回 400（实测：数组里混进一个不以 / 开头的路径，整批请求直接失败），那一页的数字会全部不显示——「全对才给」的严格口径，换来的是前端永远不用处理"部分成功"。

[!NOTE] 「9 条路径」只是那一刻的快照，别当成固定值：请求体长度永远等于线上文章数 + 1（多出来的 / 是侧栏那个全站访问量）。文章数一变，这个数字就跟着变。

列表页按热度排序：索引对齐才是真难点

列表页的排序完全在客户端做（src/scripts/post-list-sort.ts）。文章数据在构建时就被塞进页面：

window.__PAGE_POSTS_DATA__ = pagePostsData;

这段在 src/pages/[...page].astro 里，pagePostsData 是 id / title / published / pinned 四个字段的精简对象。排序脚本拿到它之后一次读完，再靠下标把数字分回去：

views[0] 是全站访问量，写进侧栏的 #site-views——这一步由读取端直接做，排序脚本不掺和；
views[index + 1] 才是第 index 篇文章的量，填进卡片上那个 span，同时通过 post-views-loaded 事件广播出去，排序脚本收到后存进 viewsData 这个 Map。

排序在 getSortedIndices() 里：日期模式按 published 排（置顶优先），访问量模式按 Map 里的数字排；render() 不做 diff，直接把 article 元素按新顺序 appendChild 回容器——元素复用，只是顺序变了。

这套实现的脆弱点恰恰是它的简洁：请求数组、响应数组、__PAGE_POSTS_DATA__ 三个顺序必须完全一致。任何一边多一个、少一个、乱一个，数字就会串到别的文章上，而且不会报错，你只会觉得数字"有点怪"。换成对象数组（[{pathname, views}]）当然更稳，但接口契约已经定了，眼下改它的收益不值这个工。

这里有个尴尬的现实：写作当时线上所有计数都是 0，点「按访问量排序」看不出任何变化——每个比较都返回 0，而 V8 的 sort 是稳定的，顺序原样保留（只有按钮的 active 样式变了）。为了验证逻辑本身，我把 /batch 的响应体在浏览器里换成了模拟数据（页面代码一行没改，也没有往 D1 写任何东西）：

6 张卡片（就是当时首页那几张）按模拟计数从大到小重排：500 / 300 / 200 / 100 / 50 / 10，侧栏全站数变成 1234；
再点一次顺序按钮（「倒序」→「正序」），顺序整个反过来：10 / 50 / 100 / 200 / 300 / 500。

也就是说批量取数、下标映射、排序三件事都是通的。唯一没验证的是真实非零数据——那需要有人往表里写，而这正是当时缺的那一环；接入上报之后我用真实数据又跑了一遍，见文末补记。

防刷与缓存口径

防刷。 先说清楚：这套守卫不是防刷，是防误写。

读接口（/share、/batch）完全公开，任何人 curl 都能拿到数字。它只做了 CORS 白名单：带外域 Origin 请求时响应里根本没有 Access-Control-Allow-Origin（实测），浏览器会拦掉读取——但这拦不住 curl。
写接口 /send 会检查 Origin/Referer 的 host 是否等于配置的目标站点，不等就 204 静默丢弃。我拿一个没人访问的路径试过：带外域 Origin 时返回 204，随后用 /share 查该路径仍然是 views: 0，说明它确实没写进去。它拦的是「别的站把上报误打过来」，同样拦不住伪造 Origin 的脚本。
真要防刷得靠边缘的 WAF / 限速规则。而我这里是读接口被刷，代价只是 D1 的行读，真正要担心的是有人拿它刷用量，不是数据被篡改。

缓存。 实测两个读接口的响应头里都没有 Cache-Control（我用 Select-String 过滤响应头，一条都过滤不出来），而 POST 本身也不可缓存。所以每次浏览都会实打实打一次查询：数字永远新鲜，也意味着没有「缓存穿透」这类问题需要额外机制去补。

顺带一个反面样本：上报脚本 /tracker.js 是有缓存的（Cache-Control: public, max-age=3600），而它当时在页面上一次都没被引用——我 curl 了首页、文章页、归档、友链、赞助、隐私、工具几个页面，tracker.js 出现次数都是 0。所以那会儿的状态是：读接口跑得很勤，写接口准备好了但没人调用。写接口接上去之后，缓存反而是好事：脚本每页只下载一次的量级，被浏览器缓存住就不会反复消耗请求额度。

踩坑与注意事项

文章页看不到侧栏的「全站访问量」，首页能看到。 因为全站数字是排序脚本顺带取回来的（views[0]），而排序脚本只在列表页加载；文章页只有 PostMeta，它只取自己那一条。实测：首页 #site-views-wrapper 的 display 是 grid，文章页是 none。同一个侧栏组件，两个页面表现不一致。（已修：读取端统一后，任何页面都会把 / 带上，见补记。）
0 数据下的排序"看起来失效"。 点按钮时 active 样式会变（说明事件绑上了），但顺序纹丝不动，因为比较器对所有组合都返回 0。测排序逻辑不能只看线上表现，得先把数据换成非零的。
接口挂了要能安静地不显示。 我把 /batch 分别换成 500 和「200 + 空响应体」测了一遍：列表页、文章页都不显示任何数字，页面其他部分完全正常，控制台的 pageerror 里也没有浏览量相关的报错。空响应体当时靠一句 throw new Error('Empty response') 拦下，统一读取端之后换成了 Array.isArray(views) 检查。这个「宁可不显示，也不显示错的」兜底是免费的——因为渲染前就检查了 res.ok。
/batch 是 N 次串行查询。 Worker 源码里就是一个 for 循环，每个 pathname 单独 SELECT 一次，没有用 IN 一次查回来；而且每次请求进来还会先跑一遍 CREATE TABLE IF NOT EXISTS。写作时首页那 7 个路径就是 7 次串行查询。现在文章少看不出差别，等文章上百篇，这就是最该先改的一处（一次 IN 查询 + 把建表检查挪出热路径）。
与本文无关但顺手发现的一个报错：线上页面控制台里一直有 cookieConsentConfig is not defined（Cookie 同意横幅那个脚本）。它不影响浏览量，但它说明客户端脚本的错误最容易长期潜伏——因为很少有人天天开着控制台看自己的博客。

收尾：给想抄这套的人一份清单

判断先放在前面：静态博客要显示浏览量，下限方案是「一个只读接口 + 一次批量读 + 服务端渲染留空位」，而不是去引第三方统计的公开接口。 展示和统计是两件事，混在一起做，哪天统计服务改个接口，你就得跟着改文章卡片。

但更值得记住的是这条：显示链路和写入链路是两件独立的事。 我这套当时读得又快又稳，数字却全是 0——因为没有页面上报。它不是读数接口的毛病，是「先把读的那半截跑通、写的那半截还没接」的状态；接上 tracker.js 会让每次 PV 多 1 个请求额度（这笔账在上一篇里算过），所以我先留着了——留到当天深夜，看着满屏 0 实在难受，还是接了，过程见下面的补记。所以：如果你在自己站点上看到每篇都是 0 次，先别怀疑接口，去抓一次包看有没有 /send。

要抄的话，按这个顺序做：

定一张两列的表（pathname 主键 + views 计数），别急着存 UA/IP——那些需求九成不会实现，真要实现也该换一套表。
接口分三个：单读（/share）、批量读（/batch，请求体就用裸数组，顺序即契约）、写（/send，带 Origin 守卫并按需静默丢弃）。
前端先渲染空壳（display: none），拿到数据再亮——不要先渲染 0 再跳数。
一页上多个组件要读数时，用「队列登记 + 一个统一读取端」，别让每个组件各自发请求，也别让「只有某个页面才取得到某个数字」。
依赖下标的排序逻辑，一定要用非零的模拟数据测一遍，别拿线上的全 0 当"测过了"。
失败路径要测全：500、空响应体、CORS 被拦，三种情况下页面都应该安静地不显示数字。
读和写都要验：读接口返回 0 不等于"接口坏了"，先 curl 一次写接口，确认是「写不进去」还是「没人写」。

补记（2026-10-05 深夜）：把写入端接上，顺手统一了读取端

上面这篇发出不到两小时，我就把「只读不写」这半截补上了——满屏的 0 摆在首页上，比多花一个请求额度难受得多。动手之后才发现问题不止一个。

现象与定位

先用 curl 把两半截分开验：

# 读：接口活着，只是表里没数据
curl -s "https://t.juluo.work/share?pathname=/posts/hello-world/"
# {"pathname":"/posts/hello-world/","views":0}

# 写：拿本站 Origin 手动打一次，立刻就进去了
curl -s -X POST "https://t.juluo.work/send" \
  -H "content-type: application/json" -H "Origin: https://blog.juluo.work" \
  -d '{"pathname":"/__selftest"}'
# {"ok":true}
curl -s "https://t.juluo.work/share?pathname=/__selftest"
# {"pathname":"/__selftest","views":1}

服务端两半截都是好的，缺的是「让浏览器去调它」。 Chrome 抓包也印证了这一点：每个页面只发出 1 条 POST /batch（读），/send 一条都没有。

[!WARNING] pathname 是我自己写的测试路径，它会永久留在 D1 里（这张表只增不减）。清理命令是 npx wrangler d1 execute cf-umami --remote --command "DELETE FROM pageviews WHERE pathname LIKE '/__selftest%'" -y，需要 Cloudflare 登录态。

改动一：把 tracker.js 引进页面

src/components/layout/BodyThirdPartyScripts.astro 里加一行，跟着 viewCounterConfig 走：

{viewCounterConfig.enable && viewCounterConfig.endpoint.trim() !== "" && (
	<script is:inline defer src={`${viewCounterConfig.endpoint.replace(/\/+$/, "")}/tracker.js`}></script>
)}

tracker.js 自己会用 document.currentScript.src 推出 t.juluo.work，再按 location.pathname 报一次，不需要额外参数。实测现在每次页面浏览固定 3 个请求：GET /tracker.js（可缓存 1 小时）、POST /send、POST /batch。

[!NOTE] 下面两小节（改动二、实测）写的是第一版：读取端只问自建接口。同一夜更晚的那次改造把数据源换成了「优先 Umami、自建兜底」，读取端结构没变，但请求数从 3 条变成了 tracker.js + /send + (1 + N) 条 Umami 查询，细节见文末「再补一刀」。

改动二：读取端收拢成一个脚本

原来取数逻辑散在两处（PostMeta.astro 的内联脚本 + src/scripts/post-list-sort.ts），靠 __VIEWS_FETCHED__ 和 __PAGE_POSTS_DATA__ 两个全局标志互相让位。能用，但有个硬伤：/ 这个路径只有排序脚本会拼进去，而排序脚本只挂在列表页——所以文章页、归档页的侧栏「访问量」永远是隐藏的，同一个组件在不同页面表现不一致。

现在收拢成 src/scripts/view-counter-runtime.ts：卡片只往 __VIEWS_QUEUE__ 里登记 slug，读取端每页跑一次、请求体固定以 / 开头；回来之后 views[0] 写侧栏，其余按 slug 填卡片，最后广播一个 post-views-loaded 事件给排序脚本消费。排序脚本里那段 fetch 和「数据没到就 setInterval 轮询」的代码也一起删了，它现在只管排序。（__VIEWS_FETCHED__ 这个标志当天夜里也一并删掉了——收拢之后没有任何地方读它，留着就是死代码。）

实测（本机构建 + Chrome 抓包，第一版：读取只走自建接口）

页面	发往 `t.juluo.work` 的请求	侧栏 `#site-views`
首页 `/`	`/tracker.js`、`/send {"pathname":"/"}`、`/batch ["/", 8 篇文章]`	显示
文章页 `/posts/xxx/`	`/tracker.js`、`/send {"pathname":"/posts/xxx/"}`、`/batch ["/", "/posts/xxx/"]`	显示（改造前是 `display: none`）
归档页 `/archive/`	`/tracker.js`、`/send {"pathname":"/archive/"}`、`/batch ["/"]`	显示（改造前连请求都没有）

上报用的 pathname 和读接口用的 key 完全一致，都取自带尾斜杠的 location.pathname——这点值得特意确认一次：不带斜杠的 /posts/hello-world 会被静态资源 307 跳到带斜杠的地址，浏览器里最终就是带斜杠的形态，两边天然对齐。

再把 /batch 的响应体换成非零数据跑一遍排序：8 张卡片按 85 / 78 / 78 / 78 / 72 / 36 / 16 / 2 从大到小重排，再点一次顺序按钮整个反过来，和前面用模拟数据得到的结论一致。

遗留

侧栏那个「访问量」是首页 / 的 PV，不是全站所有路径求和。 想要真·全站合计，得给 Worker 加一个 SUM(views) 的接口——那是另一个仓库，这套前端改不动它。（这条下一节就绕过去了：改用 Umami 之后，全站数字直接读它的总 PV。）
/batch 仍是 N 次串行查询（踩坑 4），文章上百篇之前得先改成一次 IN 查询。
踩坑 5 那个 cookieConsentConfig is not defined 还在：它跟浏览量无关，但确实说明客户端报错最容易长期潜伏——毕竟没人天天开着自己的控制台。

再补一刀（同一夜更晚）：数据源改成「优先 Umami，自建退成兜底」

上面那套修完，数字确实是真的了，但全是从零开始的真：D1 里第一行数据诞生于今晚，而 Umami 从 2025 年 8 月就在记这个站。读者点开一篇文章看到「1 次」，不会觉得「这站刚上线」，只会觉得坏了。

所以数据源换了个顺序：先读 Umami，读不到再用自建的 D1 补。

先说清楚：这篇前面写过「不用第三方统计的 API」

第三节我列了三条理由不用它。现在等于自己打脸，所以把话说透——这次能用，是因为兜底还在：

我用的不是统计后台的通用分析接口，而是分享页自己在用的那两个只读接口，拿回来的就是两个整数（pageviews），没有来源、设备、地区这些维度；
shareId 本来就是公开的（导航栏「统计」直接指向分享页），不需要任何密钥、不泄露账号；
最关键的一条：它随时可能变。这是无文档的内部接口，参数是我照着分享页抓包 + 对着 umami 源码对出来的。所以 D1 那条链路一行不删，tracker.js 继续上报——Umami 挂了，数字照常显示，只是换成自建那份。

怎么读：一条分享 token + 两个请求头

GET  {gateway}/api/share/{shareId}                      -> {"websiteId":"842d…","token":"<JWT>"}
GET  {gateway}/api/websites/{websiteId}/stats?startAt=0&endAt=<毫秒>          -> 全站全时段 PV
GET  {gateway}/api/websites/{websiteId}/stats?…&path=eq.%2Fposts%2Fxxx%2F     -> 该路径全时段 PV
     header: x-umami-share-token: <token>      # 10 分钟有效
     header: x-umami-share-context: <shareId>  # 少这个一律 401

两个坑都是抓包抓出来的：

少了 x-umami-share-context 就是 401。 我一开始只带了 token，怎么调都是 {"error":{"message":"Unauthorized"}}，换成浏览器里发也一样。翻 umami 源码才看到那段判断：拿到了 share token 还要检查分享上下文头，否则打日志 Share token used outside share context 直接拒掉——它防的是把别处签发的 token 拿来读分析数据。
网关是分区的。 后台在 cloud.umami.is/analytics/us/，数据接口却在 gateway-us.umami.is。换区部署的话这个域名要跟着换，src/config.ts 里的 umamiConfig.shareApiBase 就是给它留的。
网关填错不会报错，只会静默全 0。 这条是事后审计时才补测的：同一个 shareId，gateway-us 和 gateway-eu 都能换到 token（这个接口跨区），但数据只认网站所在的区——查到别的区返回的是 HTTP 200 + 全 0，不是错误码。而 0 在前端眼里是合法数字，所以它不会触发兜底，页面就安安静静显示 0。换区时务必打开自己的分享页、在 Network 里核对域名，别凭记忆填。

代码怎么改的：一个读取端，两个数据源，按缺口回落

src/scripts/view-counter-runtime.ts 现在做三件事：

收集本页要显示的路径（文章 slug + ViewsCounter 登记的任意路径，比如 /cover/）；
并发问 Umami：全站 1 条、每个路径 1 条；token 缓存在 sessionStorage（8 分钟），401 时丢掉重取一次；
只把 Umami 没给到数字的那些路径，凑成一个数组发给自建 POST /batch 补齐。

合并时是 {...自建, ...Umami}——Umami 优先，自建只填缺口，不做加法。两边数的是同一批访问，加起来就重复了；这也意味着 D1 里那条从零开始的曲线不会污染 Umami 的历史数字。

顺便把侧栏的体感调了一下：全站那一次请求单独接出来先画，不用等最慢的那篇文章。

实测（本机构建 + Chrome 抓包，全是线上真数据）

场景	结果
首页	侧栏 2229（Umami 全时段 PV，+2.2s 出现）；8 张卡片 +3.5s 全部亮起：12 / 12 / 7 / 1 / 1 / 1 / 0 / 0
文章页	侧栏 2229 + 该文 PV，只有 2 条 Umami 请求（全站 + 本篇）
掐断 `gateway-us.umami.is`	自动回落到 `POST /batch ["/", "/posts/…"]`，栏目照常显示（我用 111 的假数据肉眼确认回落生效）
强制所有 stats 返回 401	换 token 重试一次仍失败 → 回落自建接口，页面无报错、数字不跳 0

有一处得说清楚：Umami 那个站是 2025-08 建的，路径表里还留着 /peroe、/posts/fullstack-ssr 这类旧站路径，所以全站 2200+ 里有一部分不是现在这个站的访问。介意的话在 Umami 后台重置统计数据，或者把侧栏改成只认某段时间。

更新后的遗留

每页要打 N+1 个请求给 Umami（首页 9 条：全站 1 + 8 篇），比自建那一次 /batch 重；换来的是「数字和 Umami 后台对得上」。要降请求数，可以换成一条 metrics?type=path&limit=100 拿全部路径——但那个口径是**访客数（UV）**不是浏览量（PV），和卡片上的「N 次」对不上，所以我没选。
数字出得慢一点：Umami 这边冷启动约 2～4 秒才亮全（自建是 200 毫秒级）。数字是「先藏后显」的，所以代价只是晚一点出现，不会先给个错的。
自建那份现在只剩兜底价值，但必须留着：tracker.js 继续上报，Umami 一变脸它立刻顶上。
踩坑 5 那个 cookieConsentConfig is not defined 依然在。

中间跳丢包 90% 需要管吗：一次 traceroute 误读的完整拆解

Mon, 05 Oct 2026 14:05:00 GMT

上一篇给博客做全国 Ping 体检测出：Cloudflare 免费套餐在国内访问平均 233ms。这次我想知道得更细一点——这 200 多毫秒，到底花在路径上的哪些路由器了？

于是我在 tcptest.cn 上跑了一次从福建泉州电信到 blog.juluo.work 的在线路由追踪。结果第一眼挺吓人：中间连续几跳的丢包率是 99%、87%、97%。

只看这三个数字，结论应该是"电信骨干网崩了"。可博客当时打开得好好的，多节点 Tcping 也显示 443 端口正常（数据见上一篇）。

[!NOTE] 本文数据均为 2026-10-05 晚实测：多节点数据来自 tcptest.cn 的在线路由追踪（福建泉州电信节点，每跳 100 个探测包）；本机数据来自 Windows 上的 tracert、ping 和一段 TCP 连接测试脚本。所有截图都来自真实执行结果。

那张追踪表到底显示了什么

把关键几跳摘出来（丢包率一列是按 100 个探测包统计的）：

跳	IP	归属	丢包率	平均延迟
1	117.24.4.1	中国福建泉州/电信	0%	2ms
2	10.254.94.5	运营商内网	14%	2ms
3	—	—	100%	—
10	117.24.2.161	泉州电信 AS133776	0%	7ms
11	27.152.191.5	泉州电信 AS133776	99%	8ms
12	—	—	100%	—
13	202.97.57.145	骨干网/电信 AS4134	87%	21ms
14	202.97.12.206	骨干网/电信 AS4134	97%	24ms
15	202.97.59.62	骨干网/电信 AS4134	12%	207ms
16	81.173.18.74	欧洲/电信 AS4134	12%	215ms
19	104.21.6.247	Cloudflare AS13335（目标）	10%	196ms

这张表里有三处"自相矛盾"的地方，正是它们救了这次判断：

丢包 99% 的那一跳，延迟反而特别漂亮。第 11 跳最快 8ms、最慢 8ms、平均 8ms；第 14 跳更整齐，四个值全是 24ms。链路真丢包时伴随的是排队和延迟抖动，不会是"漏回来的包一个比一个准时"。
第 12 跳 100% 丢包，可第 13、14 跳还在回话。如果路径真在第 12 跳断了，后面的跳不可能有回包。100% 只代表"这台设备压根不打算理你"。
末跳只丢 10%。第 19 跳的 IP 104.21.6.247 就是目标本身，它丢 10%、平均 196ms——站点是通的。

真正值得留意的其实是第 15 跳：延迟从 24ms 一步跳到 207ms，而且是离开电信骨干网（AS4134）之后。这不是丢包，是出境绕路——报文从泉州走到电信国际出口，再绕经电信的境外节点（表里标注为"欧洲/电信"，地理位置仅供参考），最后交给 Cloudflare 的 Anycast 边缘。上一篇测到的"全国平均 233ms"就是这么来的：绕路，而不是链路损坏。

为什么中间跳会"丢包"：控制平面 vs 转发平面

要读懂这些数字，得先接受一个事实：路由器不是一台电脑，它至少有两套干活的方式。

转发平面（Forwarding Plane）：拆包头、查路由表、把包从某个口扔出去。这件事由专用芯片（ASIC / NP）完成，线速运行，你的网页请求、API 调用、视频流全走这条路。
控制平面（Control Plane）：跑路由协议、维护转发表，以及处理各种"需要 CPU 想一想"的杂事。生成 ICMP 错误报文，就属于这一类。

traceroute 的原理是发出 TTL 依次为 1、2、3… 的探测包，逼路径上第 N 台路由器把 TTL 减到 0，然后由它生成一个 ICMP Time Exceeded 报文（RFC 792 定义）回给你。关键在于：这个 ICMP 属于"额外劳动"，和转发你的数据没有任何关系。

而一台骨干路由器面对的是整个互联网。全世界每时每刻都有人在探测它，如果它对每个 TTL 超时的包都老老实实生成 ICMP，CPU 会被这种毫无价值的活打满。所以运营商和设备厂商的通行做法是给 ICMP 生成限速：Cisco 上有 ip icmp rate-limit unreachable 这类命令，运营商侧普遍部署 CoPP（Control Plane Policing）策略；IETF 的 ICMP 过滤建议也把"限速"列为推荐手段。

结果就是：traceroute 里的"丢包率"，统计的是这台路由器愿意回 ICMP 的比例，而不是它转发你数据时丢包的比例。 第 11 跳的 99% 只是说"100 个探测包它只回了 1 个"；第 14 跳的 97% 也只是说"它只回了 3 个"。

区分限速和真丢包，最省事的办法是看被限速那一跳漏回来的包的延迟：

控制平面限速：漏回来的包延迟低且稳（本例 8ms / 21ms / 24ms，最快最慢几乎一样）。因为链路根本不堵，只是路由器懒得理你。
真拥塞：延迟明显抬高，而且最快 / 最慢 / 平均三个值会拉开很大差距——排队是随机的。

我自己电脑上那次更离谱的误读

讲完别人的数据，说说我在自己机器上踩的坑。为了给这篇文章配一张本机 tracert 的图，我在 Windows 上跑了：

tracert -d blog.juluo.work

只出来一跳，而且第一跳就是目标 IP。

换 tracert -d 8.8.8.8、tracert -d www.baidu.com，一样只有一跳。原因不在运营商，在我自己机器上：我开着 TUN 模式的代理，route print -4 里两条默认路由，走 TUN 网卡（198.18.0.0/15 那段，metric 0）的那条优先级更高，所有流量——包括 ICMP 探测包——都在本地被代理栈接管了。测量点在代理里面，测出来的自然不是真实路径。

顺手做的另外两个测试同样不可信：

ping -n 20 blog.juluo.work

20 个包丢 9 个，45% 丢包。拿着这张图去问人，大概率会得到"你的服务器在丢包"的答案。但看仔细一点：成功的 11 个包，最快 275ms、最慢 287ms，极差只有 12ms。这种"丢得厉害、延迟却极其稳定"的组合，和前面第 11 跳是同一类现象——限速，而不是拥塞。

最能说明问题的是第三个测试。我写了个二十来行的 Python 脚本，对 blog.juluo.work:443 连续建立 20 次 TCP 连接：

import socket
import statistics
import time

HOST = "blog.juluo.work"
PORT = 443
N = 20

ok = 0
times = []
for i in range(1, N + 1):
    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    s.settimeout(5)
    t0 = time.perf_counter()
    try:
        s.connect((HOST, PORT))          # 只做三次握手，不发业务数据
        dt = (time.perf_counter() - t0) * 1000
        times.append(dt)
        ok += 1
        print(f"{i:2d}  TCP {PORT} connect OK   {dt:7.1f} ms")
    except Exception as e:
        print(f"{i:2d}  TCP {PORT} connect FAIL {e}")
    finally:
        s.close()
    time.sleep(0.2)

print(f"\nsuccess = {ok}/{N}, failed = {N - ok}")
print(f"min = {min(times):.1f} ms, avg = {statistics.mean(times):.1f} ms, max = {max(times):.1f} ms")

20 次全部成功，最快 1.0ms。

1.0ms 是什么概念？从本机到最近的中国香港机房，物理距离在 1000 公里以上，光在光纤里跑一趟就要 5ms 起步，往返一次 10ms 打底，一次 TCP 握手（SYN → SYN-ACK → ACK）不可能 1ms 完成。这个数字唯一合理的解释是：连接被本机代理栈直接终结了——代理先替远端回掉 SYN，再去慢慢建真正的连接。也就是说，这场测试测的是我的代理，不是我的博客。

[!WARNING] 这三组本机数据我照样放进文章，但它们的结论是反的：它们证明的是"在带 TUN 代理的机器上做网络测量，结果基本不可用"。排查网络问题时，先确认自己的测量点在哪一层，比多测几次更重要。

判据表：什么时候该管

把上面这些现象整理成一张表，下次再遇到"中间跳丢包"可以直接对照：

你看到的现象	大概率是什么	要不要管
中间某跳 90%+ 丢包，但漏回来的包延迟低且稳定	控制平面对 ICMP 限速	不用管
中间跳 100% 丢包（连 IP 都不显示）	设备被配置为不响应 TTL 超时（沉默设备）	不用管，看它后面的跳有没有回包
中间跳丢包，同时该跳延迟明显抬高、最快最慢差距很大	可能是真拥塞，也可能是限速叠了偶发排队	先观察，最终按末跳定论
末跳（目标 IP 自己）持续丢包 > 5%，且延迟抖动明显	真丢包：边缘节点异常或链路拥塞	要管
从某一跳开始延迟阶梯式上升（如 24ms → 207ms）	路由绕路 / 出境，不是丢包	想优化延迟才管
只有 ICMP 丢包，TCP 业务正常（页面能开、SSH 不断）	ICMP 被策略丢弃或限速	不用管
ICMP 和 TCP 同时丢，并且有用户报障	真故障	立刻管

配套的三条实操建议：

以末跳为准。中间跳只提供"路径长什么样"的信息；能不能通，只看最后一跳是不是目标 IP、有没有回包。Windows 自带的 tracert 每跳只发 3 个包，样本太少，看丢包率基本没有意义。
多打几次、多换源。每跳发 100 个包的 mtr 式工具（tcptest.cn 的路由追踪就是这种）比 tracert 可靠得多。换一个检测点再看：如果只有部分中间跳丢、末跳一致正常，基本可以定性为限速。
直接问业务端口。TCP 握手能否成功、TTFB 多少，才是用户真正感知到的东西。ICMP 只是尽力而为的旁证，从来不是指标。

那这次到底要不要管

不必。

末跳丢包 10%、平均 196ms，目标可达，业务侧 TCP 连接正常；
87%~99% 的那几跳，延迟只有 21~24ms，是最典型的控制平面限速特征，没有任何拥塞迹象；
唯一真实存在的问题，是第 15 跳之后从 24ms 涨到 207ms 的出境绕路——这属于 Cloudflare 免费套餐 + Anycast 的固有代价，和"丢包"是两件事，上一篇已经算过这笔账，暂时不动它。

小结

traceroute 的"丢包率"是 ICMP 回包率，不是转发丢包率。中间跳丢 99%，和你的网页能不能打开没有直接关系。
区分限速与真丢包的关键：漏回来的包延迟是否正常。延迟低而稳 = 限速；延迟高而抖 = 拥塞。
只有末跳（目标自己）持续丢包，才轮到"该管"这两个字。
测量前先看自己的测量点在哪一层：一个 TUN 代理就能让 traceroute 只剩一跳，让 TCP 握手变成 1ms。

[!NOTE] 数据与截图说明：多节点路由追踪数据为 2026-10-05 晚在 tcptest.cn 实测（福建泉州电信节点，每跳 100 个包，完整结果见上面的 tcptest.cn 路由追踪结果）；本机 tracert、ping -n 20 与 TCP 连接测试均为同一晚在本机执行的真实输出，未做任何改动。由于本机 TUN 代理会让 tracert 只剩一跳，原计划做的"本机多目标 tracert 对比"拿不到任何中间跳数据，中间跳的分析因此改用 tcptest.cn 的节点侧追踪结果。

同属「工具输出怎么读」的另一篇是 SSL Labs 评分：一个看网络路径，一个看 HTTPS 配置。

SSL Labs 给我博客打了个 B：HTTPS 配置到底被扣在哪

Mon, 05 Oct 2026 13:50:00 GMT

「你的 HTTPS 配置能打几分？」——以前我对这个问题的回答是「Cloudflare 托管的，能有什么问题」。直到把域名丢进 SSL Labs，四个边缘节点整整齐齐，全是 B。

[!NOTE] 站点环境：Astro 静态站，Cloudflare Worker peroe-blog（静态资源模式），免费套餐，域名 blog.juluo.work。本文所有评分、协议版本、证书信息都是 2026-10-05 晚本机实测：SSL Labs 报告时间 Mon, 05 Oct 2026 13:17:03 UTC，引擎版本 2.4.3，评级规则版本 2009q。

先说清楚 SSL Labs 在测什么

搞清楚工具的边界，比拿到分数重要。

SSL Labs 只做一件事：模拟几十种客户端去跟你的服务器握手，然后根据「你支持哪些协议版本、哪些密码套件、证书链可不可信、有没有已知漏洞」打分。它测的是传输层。

它不看这些东西：

HSTS 有没有开（只影响你能不能从 A 爬到 A+）
明文 HTTP 会不会跳转 HTTPS
Content-Security-Policy、X-Frame-Options、Referrer-Policy 这些响应头
Cookie 的 Secure / HttpOnly 属性、页面里的混合内容

所以 B 不等于不安全，A+ 也不等于安全。我这个站的安全响应头体检是 F（写在另一篇里），跟这份 B 分说的是两件完全不同的事。两份报告放在一起看才有意义。

不过有一点是可以先下判断的：对个人博客来说，TLS 这一层基本是白送的——证书是 Cloudflare 的 Universal SSL 自动签发续期，协议栈是 Cloudflare 的，我一行配置都没写过。既然我这边成本为零，那分数低就只可能是某个开关没拨。

第一步：让 SSL Labs 跑一遍

直接怼 URL：https://www.ssllabs.com/ssltest/analyze.html?d=blog.juluo.work。

几个实测出来的细节：

有缓存。 同一个域名 24 小时内的结果会直接从缓存给你，页面顶部会写 Assessed on 的时间。所以第一次跑完要等，后面再打开就是秒出。
慢。报告里每个节点的 Duration 分别是 104.78 / 103.948 / 104.164 / 104.147 sec，也就是单节点 100 秒出头。
节点是 4 个。 两个 IPv4（172.67.135.130、104.21.6.247）加两个 IPv6（2606:4700:3033:0:0:0:6815:6f7、2606:4700:3035:0:0:0:ac43:8782），串行扫完 5 分钟以上。

结果是这样：

网页版的柱状图只能目测，想要结构化数据可以直接打它的公开 API——不需要注册，也不需要 key：

curl -s "https://api.ssllabs.com/api/v3/analyze?host=blog.juluo.work&all=done" \
  | jq '.endpoints[] | {ip: .ipAddress, grade: .grade}'

返回里三个关键字段：grade = B、gradeTrustIgnored = B、hasWarnings = false。最后一个说明它不是靠「有警告」压下来的，是硬扣。

第二步：点开端点详情，看它到底扣在哪

报告首页只给结论，点进任意一个 IP 才是明细。

Summary 那一栏用四条横幅把话讲得很直白：

横幅	颜色	含义
This server supports TLS 1.0 and TLS 1.1. Grade capped to B.	黄	唯一的扣分项：老协议还开着，直接封顶 B
This site works only in browsers with SNI support.	蓝	提示信息，不扣分
This server supports TLS 1.3.	绿	加分项
This server supports PQC (Post-Quantum Cryptography) key exchange.	绿	加分项

再看它上面那四根柱子（Certificate / Protocol Support / Key Exchange / Cipher Strength）：Certificate 是满格，Key Exchange 和 Cipher Strength 目测都在九成上下，只有 Protocol Support 明显凹下去一截。柱子图形状和黄条说的完全一致——A 掉到 B，中间没有第二个原因。

第三步：用 openssl 在本机复现一遍

第三方报告的结论我不太愿意直接抄，得能自己复现。Windows 上 Git for Windows 自带 openssl（C:\Program Files\Git\usr\bin\openssl.exe，我这儿是 3.5.5）。

# 1. 正常握手：看协商到哪个版本、哪个套件
openssl s_client -connect blog.juluo.work:443 -servername blog.juluo.work -brief

# 2. 指定老协议：看服务端拒不拒（SECLEVEL 的坑见后文）
openssl s_client -connect blog.juluo.work:443 -servername blog.juluo.work \
  -tls1_1 -cipher 'DEFAULT@SECLEVEL=0' -brief

# 3. 看证书本身
openssl s_client -connect blog.juluo.work:443 -servername blog.juluo.work 2>/dev/null \
  | openssl x509 -noout -dates -subject -issuer -ext subjectAltName

实测结果：

正常握手：Protocol version: TLSv1.3、Ciphersuite: TLS_AES_256_GCM_SHA384、Negotiated TLS1.3 group: X25519MLKEM768、Verification: OK。另外单独用 -alpn h2,http/1.1 测，ALPN 协商出来的结果是 h2。
指定 -tls1_1：握手成功。Protocol version: TLSv1.1、Ciphersuite: ECDHE-RSA-AES128-SHA、Signature type: rsa_pkcs1_md5_sha1。指定 -tls1 同样能握上。作为对照，-tls1_2 走的是 ECDHE-ECDSA-CHACHA20-POLY1305。
证书：subject=CN=juluo.work、issuer=C=US, O=Google Trust Services, CN=WE1，有效期 Oct 5 08:44:00 2026 GMT → Jan 3 09:43:41 2027 GMT，SAN 覆盖 juluo.work、blog.juluo.work、*.blog.juluo.work。

两条一对比，SSL Labs 的结论就落地了：新协议没问题，是老协议没关。

顺手再用 Cloudflare 文档里给的命令对照一次（这条测的是「有没有被拦住」）：

curl https://blog.juluo.work -svo /dev/null --tls-max 1.1

文档说如果被 Cloudflare 拦下，会报 error:1400442E:SSL routines:CONNECT_CR_SRVR_HELLO:tlsv1 alert。我这儿返回的是 HTTP/1.1 200 OK——没拦。

逐项过一遍：哪些分值得修

1. TLS 1.0 / 1.1 还开着 —— 唯一的真扣分，值得修

为什么它扣分。 TLS 1.0（1999 年）和 1.1（2006 年）的 CBC 模式有 BEAST、Lucky13 这一类问题，而且不支持现代 AEAD 套件。SSL Labs 的规则很干脆：只要服务端还接受这两个版本，总分封顶 B，其它项再漂亮也没用。API 里还能看到 vulnBeast: true——它其实是「TLS 1.0 开着」的副产品，不是第二个独立问题。

关掉的代价是什么。 会连不上的是不支持 TLS 1.2 的客户端。2026 年这类客户端基本只剩：Android 5.0 以前的老系统浏览器（对 TLS 1.2 的支持不完整）、Windows XP 和没打过补丁的 Windows 7 上的老 IE、一些工业与嵌入式设备。对一个技术博客的读者群体来说，这个比例约等于零。

怎么改。 Cloudflare 面板 → SSL/TLS → Edge Certificates → Minimum TLS Version，选 TLS 1.2。文档里的 Availability 表写得很清楚，免费套餐就能用，不需要 Advanced Certificate Manager。

也可以用 API 一次改掉：

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/settings/min_tls_version" \
  --request PATCH \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{"id": "min_tls_version", "value": "1.2"}'

[!WARNING] 诚实交代两句：第一，我没有真的去拨这个开关，因为改的是线上 zone 的配置，我不想在写文章的过程中动生产环境。所以「改完就是 A」是按 SSL Labs 的封顶规则推的，不是我实测出来的，别当成已验证结论。第二，我也解释不了这个 zone 的最低版本为什么是 1.0——面板里看不到这个设置的历史，我只能确认现状是服务端接受 TLS 1.0/1.1，别看到自己的站也这样就以为配置被人动过。

我的判断：修。 不是因为「TLS 1.0 很危险」——浏览器早就不用它了，真实风险很低——而是因为这是一个开关、十秒钟、零可感知代价的事。

2. 「This site works only in browsers with SNI support」—— 不用管

说的是服务端强制要求 SNI。没有 SNI 的客户端（Windows XP 上的 IE6、老 Java 之类）拿不到证书。这是 Cloudflare 的固定行为，免费套餐也改不了，而那些客户端本来就该淘汰了。

3. OCSP Stapling: No —— 报告里列了，但没有扣分

端点详情里 OCSP Stapling 是 No，DNS CAA 是 No (more info)。我特意回头核对了一遍：评级横幅里没有任何一条提到它们，柱状图里也没有对应的扣分条。 这两项是列给你看的信息，不是扣分点，不值得为了分数去折腾。

CAA 那条更跟 TLS 握手无关——它管的是「授权哪些 CA 能给 juluo.work 签证书」，属于证书治理，不是配置错误。

4. 密钥交换和套件强度已经很好了，别乱动

从 API 拿到的结构化数据：

namedGroups 的第一项是 X25519MLKEM768，namedGroupType 标着 PQC——抗量子的混合密钥交换，免费套餐默认就开。
forwardSecrecy: 2，现代套件全部支持前向保密。
supportsRC4: null，RC4 没开；compressionMethods: 0，没有 CRIME 风险。
zeroRTTEnabled: 0，0-RTT 是关的（0-RTT 有重放风险，关着是好事）。

结论：这四项别碰。 看到「可自定义密码套件」就手痒去关掉一堆，是典型的负收益操作——Cloudflare 的默认套件列表比大多数人手写的都更合理。

那些 SSL Labs 根本不看的东西

这一节大概是全文最该记住的部分。

前面提过它只测传输层，具体到我这个站：

HSTS 没开。 API 里 hstsPolicy.status 是 absent，curl -D - 拉下来的响应头里也确实没有 Strict-Transport-Security。但这事跟 B 分毫无关系，它只在你已经拿到 A 之后决定你能不能到 A+。
明文 HTTP 不跳转。 实测 http://blog.juluo.work/ 直接返回 200 OK，没有任何 301。SSL Labs 不管这个，因为它是个纯 HTTPS 扫描器。但从「防降级攻击」的角度看，这一条比 TLS 1.0 值钱得多。
安全响应头一个都没有。 CSP、X-Frame-Options、Referrer-Policy 全是缺的，那是另一份体检报告的 F 分，跟 TLS 两码事。

所以「冲 SSL Labs A+」这个目标本身就要打个问号：它只覆盖了 HTTPS 配置里的一条线。

普通博客值不值得折腾 A+

我的判断分三档：

B → A（关掉 TLS 1.0/1.1）：值得，可以立刻做。 一个开关、零代价。哪怕不为分数，少支持两个 1999 / 2006 年的协议也没有坏处。
A → A+（加 HSTS）：可以做，但要先理解代价。 A+ 的条件是在 A 的基础上开 HSTS 且 max-age 足够长。HSTS 的真实风险不是「被攻击」，而是你自己被锁在门外：浏览器把策略缓存了，万一证书链出问题（Universal SSL 续期失败、你临时换成自签证书测试），访问者看到的是一个跳不过去的错误页。所以我建议的顺序还是「先开 Always Use HTTPS → 加短 max-age 的 HSTS 观察 → 稳定后再逐步爬坡」，preload 不用碰，展开写在那篇响应头的文章里。
为了 A+ 去手改密码套件、折腾 OCSP、加一堆用不上的东西：不值。 分数上去了，实际风险没变，却很容易搞出「某些客户端连不上」这种只有自己不知道的故障。

一句话：TLS 分数低，通常不是配置差，而是某个默认开关没拨。 花十分钟把 B 修成 A 是划算的；为了从 A 爬 A+ 反复折腾，对一个个人博客来说就是自娱自乐了。

踩坑与注意事项

坑 1（差点被误导）：OpenSSL 3.x 默认 SECLEVEL=1，直接测 TLS 1.1 会得到「假阴性」。 我第一次跑 openssl s_client -tls1_1 拿到的是 no protocols available，看起来就像「服务端拒绝了老协议」。其实那是客户端自己不肯用——OpenSSL 3.x 把 TLS 1.2 以下的协议划归过低的 SECLEVEL。必须显式降级才行：-cipher 'DEFAULT@SECLEVEL=0'。不加这个参数，我会得出「我的站最低已经是 TLS 1.2」的错误结论，然后跟 SSL Labs 的 B 分对不上，再去怀疑 SSL Labs 报错了。看到工具报错，先确认报错的是哪一方。
坑 2：SSL Labs 的网页对自动化很不友好。 analyze.html 会不停自我导航（URL 后面反复挂 &latest）去轮询进度，用一个固定选择器等结果很可能永远等不到——我按 #rating_grade 等了整整 5 分钟也没出现。要结构化数据就直接用 API；要截图就等缓存落定后再重新打开一次页面，第二次是读缓存，秒出。
坑 3：同一个域名会返回两张证书，别以为数据对不上。 Cloudflare 同时部署了 RSA（WR1）和 ECDSA（WE1）两张证书，服务端按客户端能力挑一张。所以 openssl 协商到的是 WE1（ECDSA P-256），而 SSL Labs 报告里排第一的是 RSA 2048 的 WR1，两张的 notAfter 还差了几分钟（09:43:41 对 09:40:49）。谁都没错。
坑 4：PowerShell 里调 openssl，2>&1 之后拿到的不是字符串。 openssl s_client 把 Connecting to ... 写在 stderr 上，我用 2>&1 合并后直接 Out-File，PowerShell 顺手把 NativeCommandError 的整块报错（所在位置行:4 字符:15 那一坨）也写进了文件，第一版终端配图直接报废。要么走 cmd /c "... < NUL 2>&1"，要么在管道里显式 "$_" 转成字符串。
坑 5：Worker 静态资源模式的站，「SSL/TLS 加密模式」是个伪命题。 几乎每篇教程都让你把加密模式设成 Full (strict)。但这一项管的是 Cloudflare → 源站 那一段：Flexible 是回源走明文，Full 是不校验证书，Full (strict) 才校验。我的博客是 Worker 静态资源模式，资源就在 Cloudflare 边缘，根本不存在「源站」这一段，所以 Off / Flexible / Full / Full (strict) 选哪个，对我的站不产生任何实际影响。

小结

实测结论：SSL Labs 对 blog.juluo.work 的四个边缘节点全部评 B，唯一扣分项是服务端仍接受 TLS 1.0 和 TLS 1.1，评级被 capped to B。
其余项都是好的：TLS 1.3 + AEAD 套件（TLS_AES_256_GCM_SHA384）、抗量子混合密钥交换（X25519MLKEM768）、前向保密、证书链受信（Google Trust Services，SAN 覆盖 blog.juluo.work 与 *.blog.juluo.work）——这些 Cloudflare 免费套餐默认就给。
值得修的只有一个：Minimum TLS Version 改成 1.2，免费套餐可用，代价接近零。
不值得修的：OCSP Stapling、CAA、SNI 提示——要么不影响评级，要么跟 TLS 体检本身无关；更不要为了分数去手改密码套件列表。
别忘了 SSL Labs 覆盖不到的地方：HSTS、明文 HTTP 强制跳转、安全响应头，它一样都不测，而这几项对真实安全的影响不比 TLS 版本小。

我的博客响应头缺了什么：Cloudflare _headers 补课记

Mon, 05 Oct 2026 13:35:00 GMT

博客迁到 Cloudflare Workers 之后，我一直只关心两件事：能不能打开、快不快。直到有人看了我的站说了一句「你这响应头挺干净的」——干净有时候不是夸奖。去 securityheaders.com 跑了一遍，评分直接是 F。

这篇文章把体检结果、六个缺失的头分别管什么、以及我准备怎么补，一次讲完。

[!NOTE] 站点环境：Astro 静态站，部署在 Cloudflare Worker peroe-blog（静态资源模式，免费套餐，没买 Argo / Pro），域名 blog.juluo.work，构建由 Workers Builds 从 GitHub 仓库拉 main 分支跑 pnpm update-diff && pnpm astro build --force。所有检测数据都是 2026-10-05 晚本机实测。本文发布时这些响应头还没有应用，所以文中只有 before 的真实数据；after 部分给的是方案和验证方法，需要照步骤做完自己复检。

为什么静态站最容易漏掉这一环

静态站很容易让人产生一种错觉：我只是一堆 HTML 和图片，没有数据库、没有登录、没有后端逻辑，能有什么安全问题？

问题在于，安全响应头管的从来不是服务器，而是浏览器。服务器已经正确返回了内容，浏览器接下来怎么解释这些内容、允不允许别人嵌套、要不要带着 Referer 跑去外站——这些决定权在响应头手里，而 Cloudflare 不会替你写。

三条常见路线，我对比过：

Cloudflare 控制台的 Transform Rules（Modify Response Header）。不用改代码，点点鼠标就行。但配置只活在控制台里，不进仓库、不能 review、换账号就没了；免费套餐的动态规则条数也紧张。
在 Worker 里包一层 fetch，手动 headers.set()。最灵活，但对一个纯静态站来说，为了加几个响应头把整个静态资源链路接管一遍并不划算。
在静态资源目录放一个 _headers 纯文本文件。跟仓库走、跟构建走、可 diff、可回滚，Workers 静态资源原生支持。

我选第 3 条，理由很简单：这个站的部署方式是「push 到 main → Cloudflare 构建 → wrangler deploy」，配置也应该在这个链路里，而不是散落在控制台。

实测：securityheaders.com 给了 F

直接看结果：

报告时间是 05 Oct 2026 13:10:38 UTC，扫的是 https://blog.juluo.work/。六个红叉分别是：

缺失的头	报告里的建议值
`Strict-Transport-Security`	`max-age=31536000; includeSubDomains`
`Content-Security-Policy`	按站点内容自行声明
`X-Frame-Options`	`SAMEORIGIN`
`X-Content-Type-Options`	`nosniff`
`Referrer-Policy`	`no-referrer` / `strict-origin-when-cross-origin`
`Permissions-Policy`	按需关闭不用的浏览器特性

报告底部还有一块 Upcoming Headers，列着 Cross-Origin-Embedder-Policy、Cross-Origin-Opener-Policy、Cross-Origin-Resource-Policy 三个头。它们目前不计入扣分，我也没打算上：COEP / COOP 一开严格模式，站外图片和第三方 iframe 很容易一起挂掉，收益（启用 SharedArrayBuffer 之类）个人博客用不上。

再用 curl 自己确认一遍，毕竟第三方工具的结论我得自己复现：

真实输出里跟安全相关的头命中数是 0。响应里确实有一堆头，但仔细看全是 Cloudflare 自己的东西：

Server: cloudflare、CF-RAY: ...、CF-Cache-Status: HIT —— 这是「谁在处理请求」，不是安全策略。
Nel / Report-To —— 网络错误上报（Network Error Logging），属于可观测性头。它们让浏览器把网络故障上报给 Cloudflare，跟「防不防 XSS / 点击劫持」没有半点关系。
Cache-Control: public, max-age=0, must-revalidate —— 这是 Workers 静态资源的默认缓存策略，跟安全无关（后面还会用到它）。
alt-svc: h3=":443" —— 告诉浏览器可以走 HTTP/3。

所以「响应头列表很长」这件事本身很有欺骗性。

另外我顺手测了一下明文 HTTP：

curl.exe -s -o NUL -w "final_code=%{http_code} redirects=%{num_redirects} url=%{url_effective}`n" -L --noproxy "*" http://blog.juluo.work/
# final_code=200 redirects=0 url=http://blog.juluo.work/

redirects=0，明文 HTTP 直接返回 200，站点没有强制跳转 HTTPS。这一条在后面的 HSTS 部分很关键。

逐个头过一遍：作用、副作用、我的取舍

Strict-Transport-Security（HSTS）：最容易误伤的一个

HSTS 的作用是告诉浏览器「这个域以后只准走 HTTPS」，浏览器会把这个策略缓存下来，在有效期内把所有 http:// 请求在本地就改写成 https://。它挡的是降级攻击和 Cookie 劫持——一个中间人可以篡改明文 HTTP 响应里的跳转，把你按回 HTTP，而 HSTS 让浏览器压根不发那次明文请求。

但 HSTS 有个前提常被忽略：它只管「以后的访问」，不管「第一次访问」。第一次访问如果还是明文，攻击者照样有机会。所以 HSTS 必须和「强制跳转」配合用——先让服务器 301 到 HTTPS，再加 HSTS 头。我现在的状态正好是两样都缺，去 hstspreload.org 查 juluo.work 的结果很直白：

两条错误：No HSTS header，以及 HTTP does not redirect to HTTPS。这跟我上面 curl 测到的 redirects=0 完全对得上。

副作用和坑：

includeSubDomains 是一个「域级」承诺。给 blog.juluo.work 加，覆盖的是 blog.juluo.work 及其子域，我这边没有别的子域，安全。但如果直接给裸域 juluo.work 加 includeSubDomains，那么 t.juluo.work（自建统计）、icon.juluo.work（链接卡片）必须都能正常走 HTTPS，否则会一起被打死——而且是浏览器缓存级别的打死，你改回来用户也进不去。
preload 千万不要随手加。一旦提交进 Chrome 的预加载列表，撤销要走 removal form 并等好几个月；而且预加载是硬失败：证书一过期，浏览器直接报错，没有「继续访问」的按钮。hstspreload.org 页面自己也写着 Preloading Should Be Opt-In，还专门劝项目维护者别默认给用户开。
max-age 分级爬。官方建议 300 秒 → 86400 秒 → 31536000 秒这样往上加，每一级观察一阵。我打算先在 _headers 里写 max-age=300 跑一天，确认没有意外再改大。

我的结论：HSTS 该上，但顺序是「先在 Cloudflare 开 Always Use HTTPS（SSL/TLS → Edge Certificates）→ 观察一天 → 再加 max-age=300 的 HSTS → 稳定后爬到一年」。preload 暂时不碰。

Content-Security-Policy：唯一需要认真做功课的

CSP 是这六个头里最强大的，也是最容易把站点搞坏的。它用一组指令限定页面能加载哪些来源的脚本、样式、图片、iframe，是 XSS 的最后一道防线——就算某天引用的第三方脚本被投毒，浏览器也会拒绝执行不在白名单里的东西。

我为什么不直接抄一份「满分 CSP」？因为 Astro 生成的页面里有大量内联脚本。我数了一下自己的文章页，内联 <script> 有 21 个（主题切换、代码高亮、评论加载、统计初始化都是内联的）。这意味着 script-src 'self' 一加下去，页面立刻半死。

摆在面前的是两条路：

加 'unsafe-inline'：页面能跑，但 CSP 对 XSS 的防护基本归零，等于花钱买了个装饰品。
上 nonce / hash：静态站的页面是构建期生成的，nonce 需要运行时注入，得改成 Worker 渲染或者加构建插件，为一个响应头重构整站，不划算。

所以我选分期：第一期只上「结构性」指令，这几条不涉及内联脚本，几乎零误伤：

Content-Security-Policy-Report-Only: default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'self'

object-src 'none' 挡 <object>/<embed> 注入，base-uri 'self' 挡 <base> 标签劫持，frame-ancestors 'self' 挡 iframe 嵌套。先用 Report-Only 跑一周，在浏览器 Console 里看有没有误报，确认干净了再换成强制模式、再逐步往 script-src / connect-src 收紧。

顺便记一下我扒自己页面得到的外域清单，将来收紧 CSP 时要用：cloud.umami.is（Umami 统计脚本 + <link rel="preconnect">）、giscus.app（评论 iframe 和 client.js）、t.juluo.work（自建浏览量接口）、q2.qlogo.cn（头像）、cdn.jsdelivr.net 等。也就是说真要写全量 CSP，connect-src 里必须有 t.juluo.work，frame-src 里必须有 giscus.app，img-src 得放开 https:（随机图和链接卡片封面来自站外）。这类清单只能从自己页面里扒，抄别人的一定漏。

X-Frame-Options：和 CSP 重复，但还得留

作用是禁止别人用 <iframe> 把你的站嵌进去做点击劫持——把博客套在一个透明层下面，诱导用户点「发布」「删除」之类的按钮。我的站没有这类操作按钮，风险不高，但成本也接近零。

SAMEORIGIN（允许同源嵌套）比 DENY 温和一点，留了余量。副作用是：如果你哪天想在自己的另一个域上 iframe 这个博客，会被自己挡住。

需要注意它和 CSP 的 frame-ancestors 是功能重叠的：现代浏览器以 frame-ancestors 为准，X-Frame-Options 主要是给老浏览器兜底。两个都写不冲突，但值必须一致（都 SAMEORIGIN），否则一个说允许一个说禁止，排查起来很折磨。

X-Content-Type-Options：六个里最没争议的一个

只有 nosniff 一个合法值。作用是禁止浏览器「嗅探」内容类型：如果一个 .txt 文件里写着 HTML，浏览器不应该把它当 HTML 执行，而应该老老实实按服务器给的 Content-Type 处理。挡的是利用 MIME 嗅探的上传型 XSS。

它唯一的「副作用」场景是：如果你服务器把 Content-Type 配错了，以前靠嗅探还能歪打正着跑起来，加了 nosniff 之后会直接白屏（比如 .js 被标成 text/plain，浏览器直接拒绝执行）。

我实测过自己的静态资源，Cloudflare 是按扩展名给的，/_astro/fancybox.DJVvVWuI.css 返回 text/css，Layout.astro_astro_type_script_index_0_lang.DYXp3ISy.js 返回 text/javascript，都是对的，所以这个头我加得毫无心理负担。

Referrer-Policy：把默认行为写死

它控制页面跳转到外站（以及加载外站资源）时，Referer 里带多少信息。不写的话，现在的浏览器默认已经是 strict-origin-when-cross-origin：同源带完整路径，跨域只带域名。

那我为什么还要显式写一遍？两个理由：一是把行为钉死，不依赖浏览器默认值会不会变；二是防止被别的层（CDN 规则、第三方脚本）覆盖掉。代价是：如果你靠 document.referrer 做站外来源分析，跨域场景只能拿到 origin，拿不到具体路径——不过默认值本来也是这样，所以这个头基本是零成本的。

Permissions-Policy：关掉用不到的浏览器能力

用一个头批量关掉定位、麦克风、摄像头、支付、USB 这些 API：

Permissions-Policy: geolocation=(), microphone=(), camera=(), payment=(), usb=()

空括号 () 表示「谁都不允许」，是最严格的写法。副作用很直接：关掉之后你自己的页面也用不了。如果哪天想在文章里嵌一个需要定位的演示，就得回来改这个头。所以我只关了我百分百确定用不到的几项，没有照抄那种几十项的清单。它也不像 nosniff 那样零成本，属于「想清楚再关」。

方案：一个 public/_headers 文件

最终要写进仓库的就是这个文件：

# public/_headers —— Cloudflare Workers 静态资源的自定义响应头
# Astro 构建时 public/ 会原样复制到 dist/，Workers 解析这个文件并改写响应头
# （文件本身不会被当作静态资源下发，站点里看不到它）

# 第 1 阶段：先上 5 个基本没有副作用的安全头
/*
  Strict-Transport-Security: max-age=300; includeSubDomains
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: geolocation=(), microphone=(), camera=(), payment=(), usb=()
  X-Frame-Options: SAMEORIGIN

# 第 2 阶段：CSP 先用 Report-Only 跑一周，确认没有误伤再转正
/*
  Content-Security-Policy-Report-Only: default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'self'

# 顺手的收益：_astro/ 下的产物文件名带内容哈希，可以放心 immutable
/_astro/*
  Cache-Control: public, max-age=31536000, immutable

几个设计说明：

为什么放 public/。 wrangler.jsonc 里是 assets.directory = ./dist，而 Astro 会把 public/ 下的文件原样复制进 dist/，所以 dist/_headers 正好落在静态资源根目录。部署链路一个字都不用改，npx wrangler deploy 会把它一起带上去。

HSTS 先写 300 秒。 这就是上面说的分级爬坡，验证没问题再改成 31536000。

/_astro/* 那条不是安全头，是顺手捡的收益。 现在我的资源全是 Cache-Control: public, max-age=0, must-revalidate，虽然带 ETag 不会重复下载内容，但每次导航仍要走一次条件请求。实测 MainGridLayout.BQV2WkRb.css 有 288727 字节（约 282 KB），文件名里带内容哈希（BQV2WkRb）意味着内容一变文件名就变，可以放心 immutable。

别把这条件加到 HTML 上。 HTML 保持默认的 max-age=0, must-revalidate，否则发新文章读者看不到。

[!WARNING] _headers 只对静态资源响应生效，对 Worker 代码生成的响应无效。我另外两个服务——t.juluo.work（自建统计 Worker + D1）和 icon.juluo.work（链接卡片 Worker）——都是脚本模式，响应是代码里 new Response() 出来的，_headers 管不到它们，只能在 Worker 里手动 headers.set()。这一点官方文档写得很明确，别以为放个文件就全站生效了。

规则本身的几个细节（我对着官方文档核过）：

一个块 = 第一行是路径模式（/、/path/*，也支持写完整 URL），下面缩进的行是 名字: 值。
一个文件最多 100 条规则，每行含空格在内上限 2000 字符。
多个块命中同一个请求时，头会合并；同一个头被写了两次，值用逗号拼接。
想删掉某个头（默认头或者更宽规则加上的），用 ! 头名 的写法。
匹配支持 * 通配（整个模式只能有一个）和 :placeholder，匹配到的值可以在头值里用 :splat / :placeholder 引用。

怎么验证

下面几步我没法替你跑（文件还没提交上去），只能给出 after 的验证方法：

# 1. 看完整响应头，预期多出 5 个新头
curl -sI https://blog.juluo.work/

# 2. 只筛安全头，预期有输出（现在是空）
curl -sI https://blog.juluo.work/ \
  | grep -iE 'strict-transport|content-security|x-frame|x-content-type|referrer-policy|permissions-policy'

# 3. 确认 HTTP 是否跳转（先在 Cloudflare 开 Always Use HTTPS）
curl -s -o /dev/null -w '%{http_code} -> %{redirect_url}\n' http://blog.juluo.work/

# 4. 复检评分
#    https://securityheaders.com/?q=https%3A%2F%2Fblog.juluo.work&followRedirects=on

第 2 步在我本地现在是空输出，第 3 步现在返回 200（redirects=0）。做完之后这两步应该分别变成「有输出」和 301。Windows 上没有 grep，我是用 PowerShell 的 Select-String 做的等价统计（就是前面第二张截图里那条命令，结果是 0）。

踩坑与注意事项

坑 1：以为上了 Cloudflare 就有安全头。 Cloudflare 免费套餐默认只加 Nel、Report-To、Server、CF-RAY、alt-svc 这些它自己的头，六个安全头一个都不加。这些是「可观测性头」和「传输协商头」，不是「安全头」，别被响应头列表的长度骗了。
坑 2：securityheaders.com 到底扫的是 HTTP 还是 HTTPS。 我第一次直接在输入框填了域名，它按 http://blog.juluo.work/ 扫的（报告里 Site 那一行会写出来）。后面加上 followRedirects=on、并且显式写 https://，报告才是你真正想要的那份。两次结果的评级都是 F，但缺的头数量不一样（HTTP 那份是 5 个，HTTPS 那份是 6 个，多了 HSTS），很容易看错。
坑 3（差点踩）：includeSubDomains 之前先数一遍子域。 我在 blog.juluo.work 上写是安全的；但如果图省事直接给裸域 juluo.work 写 includeSubDomains，而某个子域还跑在 HTTP 上，那就是浏览器缓存级别的打死，改回来也进不去。
坑 4：CSP 不能直接上强制模式。 静态站的页面是构建期生成的一大坨内联脚本，script-src 'self' 下去评论区和统计会立刻全灭。必须 Report-Only 先跑，看 Console 报错清单。
坑 5：immutable 别加错地方。 只给带内容哈希的 /_astro/*，HTML 保持默认。加错到 HTML 上读者会一直看到旧页面，而且因为自己浏览器强刷而不复现，特别难排查。

小结

现状（实测）：六个安全头全缺，securityheaders.com 给 F，http://blog.juluo.work/ 明文返回 200 不跳转，juluo.work 不在 HSTS 预加载列表里。
值得马上补的四个：X-Content-Type-Options、Referrer-Policy、X-Frame-Options、Permissions-Policy。几乎是纯收益，副作用可以忽略。
HSTS 要配合强制跳转一起上，max-age 从 300 秒分级爬，preload 现阶段别碰。
CSP 是唯一需要认真做功课的：先用 Report-Only + 结构性指令，等内联脚本清理干净了再收紧。
Cloudflare Workers 静态资源站，public/_headers 是成本最低、最可回滚的做法：跟仓库走、跟构建走、能 diff 能 review。但它只管静态资源，Worker 生成的响应还得在代码里加。

本文发布时站点还没有应用这些头，after 数据都是方案说明而不是实测结果。照上面四条命令复检即可。

配合 HTTPS 配置的 SSL Labs 评分一起看，安全审计的两块就齐了。

关于本站

Mon, 05 Oct 2026 00:00:00 GMT

欢迎来到我的博客 👋

这里是我的个人空间，主要记录技术折腾、开发笔记和一些生活碎片。

这个站点

域名：https://blog.juluo.work
技术栈：Astro + Svelte + Tailwind CSS，部署在 Cloudflare Workers 上
主题：基于 Fuwari 二次开发
统计：Umami（无 Cookie、不追踪个人）
评论：Giscus（基于 GitHub Discussions，登录 GitHub 即可评论）

怎么联系我

关于内容

文章基本都是我自己实践后整理的笔记，尽量写清楚「为什么这么做」而不只是「怎么做」。如果某篇文章帮到了你，欢迎在下方评论区留言（评论会同步到 GitHub Discussions）。

这个博客陆续写过一些实现细节，比如浏览量统计、站内搜索、给文章上密码，还有一篇讲网络排障的 traceroute 误读。

peroe 的博客

27 篇文章的站内搜索：81 KB 索引与一次 304

方案长什么样

修掉的那个问题：no-store

这套方案的天花板

一个取舍：索引里要不要放全文

小结

构建产物 16 MB，访客每次只下 28 KB

dist 里到底装了什么

但访客从没下载过这 1.6 MB

三个让差距变大的机制

顺手修掉的一个小浪费

该看哪个数字

小结

可访问性体检：三个真问题与三次假警报

六项检查，跑一遍就知道

三个真问题

三次假警报（比真问题更值得记）

现在的基线

小结

24 篇文章的站内 SEO：一套可复跑的体检清单

八项检查，扫的就是产物

九类真实问题（按影响排序）

现在的基线

三条「体检本身也会骗你」的教训

怎么复跑

小结

静态站的标签体系：挖出 11 个可收录页面

先数一遍：哪些标签值得建页

每个标签页长什么样

描述怎么生成：唯一、且够长

三个坑

顺带修的一件事：文章页显示标签

小结

和 Cookie 横幅抢 LCP：我试到哪一步就停了

三招，逐招看效果

为什么「压小」没用

还有一个隐性原因：那是第三方脚本

所以我停在这里

这轮的实际收益

小结

我的性能测试骗了我：把第三方全拦掉再测

起因

三个"测量"，三个世界

Lighthouse 说 LCP 是谁

修了什么

还没解决的：横幅仍然是最大的元素

三条教训

小结

我的博客向陌生人暴露了多少信息

第一层：证书透明度日志

第二层：DNS 里的"业务指纹"

第三层：页面本身

真正要修的那一条：头像

没改、但建议盯着的两件事

一份可复用的自查清单

小结

随机图当封面：一张 250KB，我没让它进列表

三种封面方案

它到底返回了多大一张图

算一笔账

那随机图什么时候合理

兜底：图挂了怎么办

小结

三层缓存各自为政：我的静态资源被一行 Cache-Control 拖慢

三层缓存，各管一段

问题：哈希命名的资源也被设成 max-age=0

修法：给 /_astro/ 单独加一条响应头规则

两个平台细节（写规则前值得知道）

一套可以照抄的判断表

小结

图片格式的收益边界：PNG → WebP → AVIF 实测

第一轮：按质量参数比，结论是错的

第二轮：用 PSNR 对齐画质

那为什么我还在用 WebP

什么时候值得上 AVIF

一个容易被忽略的对比维度

小结

静态博客接评论：Giscus 的配置、主题联动与三个坑

六个字段，各有各的用处

修掉的那个问题：`no-store`

约定一：`<script>` 默认不是你想的那种 script

约定三：`dist/` 从不清空