此间札记

中文网页排版，多数主题都做错了

XIAOXUsop — Sat, 12 Sep 2026 00:00:00 GMT

中文网页排版有个奇怪的现象：大家都觉得别扭，但很少有人能指出哪里别扭。

原因多半是这四个参数被直接沿用了西文的值。它们单独看都不致命，叠在一起就是那种说不清的「不对劲」。

一、行高#

西文正文的常用行高是 1.4 到 1.5。这个值搬到中文上会显得挤。

因为汉字是方块字：笔画在字面内铺得很满，字与字之间没有西文那种由升降部带来的天然空隙。同样行高下，中文的行间留白视觉上更少。

中文正文的行高应当在 1.6 到 1.8 之间。本站用的是 1.75。

还有个细节：行高要用无单位数值（line-height: 1.75），不要用 px 或 em。无单位值是相对于元素自身字号计算的，继承时不会出乱子。

二、字重#

这条最容易被忽略，但效果立竿见影。

很多中文字体只有两个真实字重：400 和 700。 苹方有 Ultralight 到 Semibold，思源黑体有 300 到 900 的完整字重；微软雅黑主要就是 400 和 700。（Apple 官方系统字体清单里列有 PingFang SC Semibold，见 System Fonts。）

这里的通行说法是「写 600 会触发伪合成，所以只能写 500」。这话只说对了一半。

伪合成的开关不是字重数值，而是 font-synthesis-weight。至于字重本身—— 写一个字体没有的字重时，规范要求的是去找最接近的真实字重，不是伪造一个：

When a weight is specified for which no face exists, a face with a nearby weight is used. —— CSS Fonts Level 4 §2.2.2

「最接近」具体朝哪边找，规范给了确定规则（§5 字重匹配）：请求的字重大于 500 时，先按升序检查不小于目标的字重（600 → 700 → 800 → 900），都找不到再向下找。于是：

苹方这类确有 600 的字体 → 请求 600 直接命中 600，不会跳到 700；
微软雅黑这类只有 400/700 的字体 → 请求 600 先查 700，落到 700。

两条路径都不会伪造粗体（前提是没开伪合成）：开着合成时它才会把 400 算法加粗——笔画发虚、字形走样，而且每个浏览器合成得还不一样。

本站的做法是把合成直接关掉：

html {
  font-synthesis-weight: none;
}

于是标题可以写 font-weight: 600：拉丁部分拿到 Archivo 的真实 600，中文部分落到自己字体里最接近 600 的真实字重（苹方约 600、雅黑 700），两者视觉重量相当。（反过来，写 500 的话中文更容易掉到 400——比正文还轻，标题反而立不住。）

更重要的是：层级主要靠字号和颜色建立，不要靠字重硬拉。 一段 17px/400 的正文和一段 21px/600 的小标题，层级已经足够了。

勘误（2026-09-22）：这一节原先写的是「正确做法：标题字重写 500，让字体自己去挑最接近的真实字重」。结论和建议都改掉了：把伪合成归因到字重数值本身是错的——开关是 font-synthesis-weight；而在关掉合成的实现里，写 500 会让中文落到 400，比 600 更糟。依据见 CSS Fonts Level 4 的字重匹配与本站 src/styles/base.css 的 font-synthesis-weight。

三、行宽#

这是四个里最麻烦的一个，因为中西文的最优值在同一个单位下对不齐。

西文的理想行宽是 45 到 75 个字符，66 是经典值。而 ch 这个单位是为西文设计的——按规范，它等于渲染所用字体里「0」字形的宽度：

ch — Represents the typical advance measure of European alphanumeric characters, and measured as the used advance measure of the “0” (ZERO, U+0030) glyph in the font used to render it. —— CSS Values and Units Level 4

两个要点：它是欧洲字符的度量，而且取决于字体。所以 ch 换算不出一个跨字体稳定的汉字数——换个字体，「66ch 能排几个汉字」这个数就变了。

粗估的话，一个汉字约等于两个 ch，66ch 大约排 33 个汉字。（顺带一提，这个数其实落在中文舒适的 30–40 字里——但它是粗估，且随字体浮动。）

本站改用 em，图的是可预测：

.prose {
  max-width: 34em;
}

em 等于元素的字号，这是规范保证的，且不依赖字体。但「一个汉字正好 1em 宽」不是规范保证——汉字的 advance 取决于具体字体，规范为此专门定义了一个 ic 单位来表示「字体中全角字形的典型 advance」，并规定在无法确定时假设为 1em：

The ic unit is … a typically exact measure (in the few fonts with proportional fullwidth glyphs, an approximation) of a single fullwidth glyph’s advance measure. In the cases where it is impossible or impractical to determine the ideographic advance measure, it must be assumed to be 1em. —— CSS Values and Units Level 4 §5.1.1

这一句本身就说明「容器宽度单位」和「实际字形宽度」不能混为一谈—— 如果规范能保证两者相等，就不必再定义 ic 了。

所以准确的说法是：34em 让内容栏宽度稳定地跟随字号；对常见全角汉字可近似理解为约 34 字，但实际每行字数仍受字体、标点、字距和混排影响。于是：

中文：约 34 个字（近似，落在 30–40 的理想区间）✅
西文：约 68 个字符（近似，落在 45–75 的理想区间）✅

一个值同时覆盖两种文字的舒适区，而且容器宽度不随字体变。 这是 --measure: 34em 的由来。注意被保证的是「宽度稳定」，不是「字数确定」。

勘误（2026-09-22）：这一节原先写的是「一个汉字大约等于两个 ch，所以按 66ch 排中文，每行会排出约 130 个汉字——远超出中文舒适的 30 到 40 字」。 两处都错：按它自己的前提应当除以 2 得 33，而不是乘以 2 得 130；而 33 本来就落在它自己说的舒适区间内，所以「远超」这个结论也不成立。

这句话还遮住了一个更关键的事实：66ch ≈ 33em，与本题采用的 34em 宽度几乎相同 （这一步依赖「0 字形约 0.5em」这个假设，是推算而非实测）。也就是说这个改动换来的是容器宽度的可预测性，不是行宽。 结论（用 em）不变，论证方式改了。

依据：CSS Values and Units Level 4 §ch、 §ic。

勘误（2026-09-24）：上一条勘误之后，本节仍留着「em 等于字号、与字体无关。一个汉字约 1em 宽……而且不随字体变」，并据此把 34em 说成确定的字数换算。前半句对，后半句越界了：规范保证的是 em 等于计算后的 font-size，不保证每个汉字的 advance 恒等于 1em——所以「34em ≈ 34 字」是近似，而「每行字数确定」这句话是不成立的。详见上面引的 ic 那段。

四、中西文间距与标点#

中文和英文、数字之间应该有一个小间隙：「共 500 条记录」比「共500条记录」好读。

过去这件事要靠 pangu.js 之类的库在客户端跑一遍正则，找到边界然后插空格。它有一堆边缘情况（全角标点前后不加、 90° 不加、15% 不加），而且要在 DOM 加载后重写文本。

2026 年浏览器原生做了这件事：

html {
  text-autospace: normal;
  text-spacing-trim: trim-start;
}

text-autospace: normal 自动在中西文之间插入约 1/4 个空格。2025 年进入 Baseline。
text-spacing-trim: trim-start 做中文标点的字距调整——行首的逗号句号之类不再占满一格。Chrome / Edge 123+ 已默认开启。

两个前提：<html lang> 必须设置正确，否则浏览器不会应用对应语言的规则；代码块里要关掉自动间距，因为代码里的空格是有意义的：

pre, code, kbd, samp { text-autospace: no-autospace; }

只有 Chromium 系支持：MDN 的浏览器兼容数据（2026-09-24 查）记 Chrome 自 123 起支持，Safari 与 Firefox 均为「不支持」—— caniuse 上还没有这个特性（太新）。所以它是渐进增强——不支持的浏览器只是少了那一点调整，版式不会坏。

本项目此前在这里写的是「全球覆盖约 72%」，现已删除。 那个数字没有任何来源（caniuse 抓不到、本项目也没实测过），而它写在一个「实测」味道很重的段落里。 一个查不到来源的覆盖率，比不写更糟——读者会以为它是量出来的。

五、一条容易漏的：中文没有斜体#

中文字体不提供斜体字形。font-style: italic 对中文的结果是浏览器 合成倾斜——把笔画整体拉斜，字形变形、笔画糊在一起。

而 CSS 没法问「这段 <em> 里是中文还是西文」。所以务实的选择是： 统一把强调处理成加粗，这也是中文排版的通行做法。

em, i {
  font-style: normal;
  font-weight: 600;
}

六、字体栈的顺序#

最后一条，顺序不能反：

font-family: 'Archivo', -apple-system, 'PingFang SC', 'Microsoft YaHei', sans-serif;

拉丁字体必须排在前面。 如果中文字体排在前面，英文也会用中文字体渲染—— 而中文字体里的拉丁字母是等宽的（为了和汉字对齐），排版上很难看。

顺序对了之后，英文用 Archivo 渲染，汉字自动落到苹方/雅黑，各取所长。

那要不要自托管中文字体#

默认不要。 中文字体单文件 5–20 MB，哪怕做了子集化，一个博客站也不该为此付出首屏时间。而中文系统字体（苹方、微软雅黑、思源黑体）质量本身就很好—— 知乎、Medium 中文版这类大站的内文都用系统字体。

实在需要自定义时，用 cn-font-split 做子集化，并且务必用 unicode-range 限定覆盖面。

小结#

参数	西文常用	中文应用
行高	1.4–1.5	1.6–1.8
标题字重	600–700	600（配 `font-synthesis-weight: none`）
行宽	66ch	34em（≈34 汉字 / ≈68 西文字符，均为近似）
中西文间距	手动加	`text-autospace`
强调	斜体	加粗

这些细节单独看都很小。但它们同时出现时，读者的感受就是「这个站读起来舒服」而说不出为什么——那正是排版该有的样子。

相关条目：中文排版、内容协商。

参考#

CSS Values and Units Level 4 §ch —— ch 的定义（W3C Working Draft, 12 March 2024）
CSS Fonts Level 4 §2.2.2 Missing weights —— 缺少字重时如何匹配
CSS Fonts Level 4 §font-synthesis-weight —— 伪合成的开关（W3C Working Draft, 13 September 2026）

为什么链接带日期而不是 /TR/css-values-4/：后者是”最新版”，会随规范修订移动——半年后回看，不知道当时引的是哪一版。 W3C 自己推荐的引用方式就是带日期的固定 URL。

修订记录

2026-09-12 发布。
2026-09-22 勘误：行宽一节把「一个汉字 ≈ 2 ch」算反了（应除以 2 得 33，原写作乘以 2 得 130），连带「远超舒适区」的结论也不成立；字重一节把伪合成归因到字重数值上，而开关其实是 font-synthesis-weight，且在关掉合成的实现里写 500 会让中文落到 400。两处的结论都保持不变（用 em、标题用 600），改的是论证与依据。同步修订了中文排版。
2026-09-24 勘误：上一轮只改了那句算错的算式，却留下了更大的越界—— 「em 等于字号、与字体无关」被推广成「一个汉字正好 1em 宽、每行字数确定」。规范保证的只是 em 等于计算后的 font-size；它为此专门定义了 ic 来表示全角字形的典型 advance，无法确定时假设 1em。同时苹方字重结论与 Apple 官方清单冲突（清单里确有 PingFang SC Semibold），且「请求 600 必落 700」是条件句：匹配算法对 >500 的请求先向上找，有真 600 的字体直接命中 600。

这个博客是怎么搭的

XIAOXUsop — Sat, 12 Sep 2026 00:00:00 GMT

这一篇是写给你的——如果你 clone 了这个项目，它会告诉你东西都在哪。

你只需要改一个文件#

src/config.ts。里面的 site、author、nav 三项改完就能上线：

export const site: SiteConfig = {
  title: '你的站名',
  tagline: '一句话说清这个站是什么。',
  url: 'https://example.com',   // 部署前填，不留斜杠
  lang: 'zh-CN',                // 别改错——浏览器的中文标点规则依赖它
  author: { name: '你的名字', bio: '一句话介绍自己。' },
  // …
};

其余全部有可用的默认值，而且默认值本身就是完整站点，不是占位符。 你现在看到的这些文章和知识库条目就是示例内容——它们是真的能读的，不是 lorem ipsum。删掉它们换成你自己的即可。

东西都在哪#

src/
├── config.ts            你唯一必须改的文件
├── content/
│   ├── posts/           文章。按时间排
│   └── wiki/            知识层。按主题互链
├── layouts/             页面骨架
├── components/          组件
├── pages/               路由
├── lib/                 纯逻辑（可测试，不依赖 Astro）
│   ├── negotiate/       Accept 头解析——[[内容协商]] 的实现
│   └── wiki/            链接图、体检、llms.txt 生成
└── styles/
    ├── tokens.css       设计令牌
    ├── base.css         基线排版（含 [[中文排版]] 的那些修正）
    └── site.css         布局与组件

两种内容，两种组织方式#

文章放在 src/content/posts/，按时间排列，是「流」。

知识库条目放在 src/content/wiki/，按主题互链，是「网」。

它们的区别不是格式，是读者找东西的方式：想看你最近写了什么就翻文章，想搞清某个概念就查知识层。两边的条目地位相同，可以互相引用。

用 `[[方括号]]` 连起来#

在任何地方写 [[目标]]，就会生成一条链接：

见 [[内容协商]] 一节。

支持三种写法：

写法	效果
`[[内容协商]]`	链接，显示文本即目标名
`[[内容协商\|那篇]]`	自定义显示文本
`[[内容协商#为什么]]`	指向页内某小节

目标可以写 slug，也可以写标题——你大概不会记得每篇的 slug 是什么。解析时大小写和空格都不敏感。

写错了不会静默失败：构建时会报一条 broken-wikilink 错误，并告诉你哪个页面引用了什么。

构建时会做体检#

每次构建会跑一遍知识库体检，输出在控制台。分三级：

错误：断链、两个页面抢同一个 URL、文章占用 /about/ 等系统路由、引用了没登记的来源、复核状态与正文对不上。 会让构建失败（可在配置里关掉）
警告：孤儿页（没有任何页面指向它）、缺摘要、空正文、同一关系在正文与 related 里各写了一次
提示：摘要过长之类的建议

这不是可选的装饰。 一个由人（或 agent）持续维护的知识库，最容易的结局是慢慢烂掉——改了标题没改引用、删了页面留下断链。机械的检查必须能进 CI，否则「知识库」会退化成「一堆文件」。

完整的规则表在 AGENTS.md——那份是写给 agent 看的，改规则时两边要一起改。

给 AI 读者那一份#

这一站有两个出口，服务两类读者：

Markdown 孪生文件。 每篇文章和知识页都有可直接访问的 .md URL。在支持内容协商的部署平台上，请求页面 URL 时带上 Accept: text/markdown 也会得到 markdown；本站使用 GitHub Pages，因此应直接访问 .md 链接。原理和托管限制见内容协商。

目录与全文。 /llms.txt 是给 agent 看的目录（标题 + 一句话说明）， /llms-full.txt 是全文内联版。每个页面还有 .md 孪生文件，比如 /how-this-works.md。

需要说明的是：llms.txt 的实际效果被高估了—— Ahrefs 实测 13.7 万个域名里 97% 的 llms.txt 从未被请求过。本站生成它是因为零成本，但主要依靠显式 .md 链接、内容清单和干净的 HTML。

部署#

静态产物，任何静态托管都能跑。但内容协商需要一层边缘函数—— 因为静态托管不解析请求头，它只会把文件原样吐出来。

项目里带了三个平台的现成实现，选你用的那个：

平台	边缘函数	平台配置
Cloudflare Pages	`functions/[[path]].ts`	`public/_headers`（会被拷进产物）
Netlify	`netlify/edge-functions/negotiate.ts`	无额外配置
Vercel	`middleware.ts`	`vercel.json`

不想要这一层也没关系，站点照常工作，只是 agent 拿到的是 HTML 而不是 markdown。

详细说明#

排版与设计决策：中文排版、设计令牌
知识层的设计取舍：LLM 知识库

你的博客该不该给 AI 一份 markdown

XIAOXUsop — Sat, 12 Sep 2026 00:00:00 GMT

一个 AI agent 抓取你的网页时，看到的东西和你看到的不一样。它看到的是两万个 token 的导航栏、页脚和 <div> 嵌套，而正文可能只占其中百分之几。

这不是比喻。Cloudflare 实测自己的文档：同一页 HTML 要 16,180 token， markdown 版只要 3,150 token——省 80%，内容一模一样。

HTTP 从 1.1 起就有解决这个问题的机制：内容协商。客户端在 Accept 头里说「我更想要 markdown，不行的话 HTML 也行」，服务端照办。

问题是：博客圈几乎没人用。

谁在要 markdown#

拿七个常见 agent 去请求 httpbin.org/headers，看它们各自发出的 Accept 头。结果是这样的：

Agent	要 markdown 吗	Accept 头
Claude Code	是	`text/markdown, text/html, /`
Cursor	是	`text/markdown`, `text/html;q=0.9`, …
OpenCode	是	`text/markdown;q=1.0`, `text/x-markdown;q=0.9`, …
OpenAI Codex	否	`text/html`, `application/xhtml+xml`, …
GitHub Copilot	否	`text/html`, `application/xhtml+xml`, …
Gemini CLI	否	通配符
Windsurf	否	通配符

七个里三个主动要。而这七行数据本身就是一份测试用例——见内容协商里关于怎么把它钉成回归测试的部分。

一个安静失败的实现细节#

Claude Code 那一行值得单独说。

它发的是 text/markdown, text/html, */*——没有 q 值。在 HTTP 里，缺省 q 值等于 1.0，于是 markdown 和 html 两个媒体范围并列。

这里要说清楚：RFC 并没有规定并列时怎么打破平局。 RFC 9110 §12.5.1 规定的是「媒体范围可以被更具体的范围覆盖，更具体的优先」—— 它按具体程度排序（text/plain;format=flowed → text/plain → text/* → */*），而对 q 值相同的两个类型，规范只说它们是 equally preferred，没有给顺序。

所以「靠前的优先」是本项目的实现选择，不是规范要求。

但如果实现里写的是严格的 > 比较：

if (markdown.q > html.q) return 'markdown';
return 'html';

那么 1.0 > 1.0 为假，判定落到 HTML 上。Claude Code 永远拿不到 markdown，而服务端不报错、不警告、日志里什么都没有。 你只会觉得「这功能好像没用」。

本项目的做法是并列时比顺序（如上所述，这是选择而非规范要求）：

if (markdown.q !== html.q) return markdown.q > html.q;
return markdown.index < html.index;

这类 bug 的可怕之处在于它不会以错误的形式出现，只会以「没效果」的形式出现。

为什么现成的工具都不太行#

Astro 生态里已经有两个包在做这件事，但都停在半路：

astro-markdown-for-agents：在构建期生成 .md 文件，但协商只在 dev server 里生效。它的 README 直说：「不包含托管平台运行时垫片；静态托管环境下的服务时协商应由使用方自行实现。」也就是说上生产就没了。
astro-markdown-export：把源 .md 复制进产物目录，完全不做协商。要访问 /slug/index.md 才拿得到，而且导出的是未渲染的源文件。

两者的周下载量分别是 106 和 17。而主流 Astro 集成是三十万到两百万。 这不是「已经解决了只是没人知道」，是「有人碰过就放弃了」。

难在哪#

难的不是算法——算法上面已经写完了，四十行。

难的是静态托管不解析请求头。静态站就是一堆文件，CDN 把文件原样吐出来，它不会因为你 Accept 写了什么就换一个文件给你。所以你需要一层边缘函数。

这也是为什么 Cloudflare 的 Markdown for Agents 要 Pro 及以上套餐—— 它是在边缘替你做了转换。而 Vercel 的实现只在自己的平台内生效。 跑在免费静态托管上的博客，两头都够不着。

出路是：构建期生成 .md 孪生文件，再用一层几十行的边缘函数做选择。转换在构建期完成（零运行时成本），边缘只负责「给哪个」。 Cloudflare Pages Functions、Netlify Edge Functions、Vercel Middleware 的免费额度都够用。

两件必须做对的事#

一、Vary: Accept 不能省。 少了它，CDN 会把 markdown 版本缓存下来发给浏览器——用户打开博客看到一坨纯文本。这是个会让人当场关掉标签页的 bug，而它只在缓存命中时出现。

二、*/* 不算「想要 markdown」。 Gemini CLI 和 Windsurf 只发通配符，意思是「给什么都行」。如果把通配符也算作 markdown 偏好，这两家会被塞 markdown——它们本来接受 HTML，你硬给别的格式，属于自找麻烦。

顺带说一句 llms.txt#

你可能想问为什么不提 llms.txt。因为它的实际效果被严重高估了：

Google 明说不需要。 Search Central 的 AI 功能文档里写着：

You don’t need to create new machine readable files, AI text files, or markup to appear in these features.

注意原文说的是「不需要」而不是「不支持」——不做也不会因此缺席，但 Google 也没说它有害。（原文）
多个独立实验都没测到可归因的效果。

这组数字曾经被删掉过，2026-09-24 找回来了。 这里原先写「Ahrefs 2026 年 5 月实测 137,210 个域名：97% 的 llms.txt 从未被请求过」。上一轮我按几种常见路径试 ahrefs.com/blog/* 全部 404、Ahrefs 自己的 sitemap 里没有收录博客，于是把整组数字删了，并写明「查不到就不该留着」。

那个删除是对的推理、错的结论：原文确实存在，地址是 https://ahrefs.com/blog/llmstxt-study/，此前只是没试中路径。 2026-09-24 重新抓取原文逐字核对，数据全部对得上：

样本：Ahrefs Web Analytics 中2026 年 5 月获得流量的全部 137,210 个域名（方法学章节原文：all 137,210 domains ... that received traffic in May 2026）；

其中 28% 发布了 llms.txt；

这些文件的 97% 在 2026 年 5 月零请求——97% of those files received zero traffic in May 2026；

有请求的那 3% 里，96% 的请求来自 bots。

发布日期与数据窗口是两件事：原文发布于 2026-06-15，统计的是 2026 年 5 月。先前的写法把两者混成了「2026 年 5 月实测」。

留着一个可点开的来源，比留着一句「查不到」更有用；但边界也要跟着一起写：这是对 llms.txt 根文件的 HTTP 200 探测，不是对「AI 有没有读到内容」的观测——被请求的 3% 里，77% 的 bots 并不是 AI 工具。

它零成本、无下行风险，而且确实有 agent 会抓（Claude Code 抓取 llms.txt 的频率高于任何 AI 搜索机器人），所以本站在生成它。但把它当卖点是误导。

真正的杠杆是干净的内容协商和语义化的 HTML——后者对静态站来说是白送的。

参考文献#

RFC 9110 §12.5.1（Accept 头）、 RFC 7763（text/markdown 媒体类型）
Cloudflare, Markdown for Agents —— 正文里「16,180 → 3,150 token、省 80%」那组数字出自这里。 测量条件是 Cloudflare 拿自己的文档做的，本项目没有复现它；它说明的是「干净 HTML 转 markdown 能省多少」，不是本站的节省率（本站自己的数字在内容协商末尾，且是启发式估算，那里附了真实词表的对照）
Google Search Central, AI features and your website —— 正文里「Google 明说不需要」那段引文出自这里
Ahrefs, We Analyzed 137K Sites: 97% of llms.txt Files Never Get Read， 2026-06-15 发布、数据窗口为 2026 年 5 月 —— 正文里 137,210 / 97% / 96% 那组数字出自这里。 测量条件是 Ahrefs 拿自己的流量数据做的，本项目没有复现它；它观测的是「根文件有没有被请求」，不是「AI 有没有读到内容」—— 被请求的那 3% 里 77% 的 bots 并不是 AI 工具
~~Ahrefs 那组数字原先作为一条独立引用，2026-09-23 被移除。~~ 2026-09-24 找到了原始地址并已恢复（见上一条）—— 那一轮的删除是对的推理、错的结论：ahrefs.com/blog/* 几个常见路径全 404 只证明了「我按这几个路径没找到」，不等于「原文不存在」。 一个找不到的路径不是不存在的证据。

勘误（2026-09-22 / 09-23 / 09-24）：这几条原先都是纯文本、点不开，已核实的补了链接； 09-23 那一轮把 Ahrefs 那条当作「核实不到」移除了，09-24 又找回来了—— 因为原文一直存在，只是当时试的路径没命中。三轮下来值得记住的是：「我没找到」和「它不存在」之间隔着一整条推理链，跳过那条链就会把一次失败的检索固化成一条结论。

静态站搜索的三种做法，以及它们各自真实的上限

XIAOXUsop — Fri, 14 Aug 2026 00:00:00 GMT

静态站没有后端，所以搜索必须换个地方放。只有三个位置：

放进浏览器、放进构建产物、放到另一台服务器上。

选哪种，取决于你愿意接受哪一种上限。

一、放进浏览器：把内容全量打到前端#

最简单：构建时把全部文章导成一个 JSON，页面加载后在前端过滤。

const results = all.filter(p => p.title.includes(q) || p.body.includes(q));

上限在「全量」两个字上。 索引就是全部正文，文章一多，用户为了搜一个词要下载整站内容。

50 篇中等长度的文章大约 1–2 MB。1000 篇就是几十 MB——搜索框还没用上，流量已经烧完了。

它适合几十篇以内的站点。超过这个量级，你会开始想「能不能只加载摘要」，而那正是第二种方案。

二、放进构建产物：只下载倒排索引#

构建时切词、建倒排索引，把索引作为静态资源发布。用户只下载索引，不下载正文；命中之后再按需取片段。

这一类的代表是 Pagefind 和 Fuse.js：

Fuse.js 是纯前端模糊匹配，仍然需要你把待搜内容喂给它——所以它解决的是「怎么匹配」，没解决「内容放哪」
Pagefind 是构建后跑的索引器，直接读你的 HTML 产物。它把索引切成小块，搜索时只加载相关分片——这才是真正的「索引比正文小」

Pages/Netlify 这类托管上，Pagefind 是当前最省事的选择：一条命令，零后端，还能按语言分别处理。

上限在分词上。

Pagefind 对中文不做词干提取——中文本来也没有词形变化，所以这不影响正确性。真正的影响是召回：它按字/词切分建索引，你搜「排版」能命中包含「排版」的段落，但搜「网页排版」不一定能命中只写了「排版」的地方。

英文靠词干回退（running ↔ run）缓解这类问题，中文没有对应机制。 这是静态站搜索的固有限制，不是某个库的缺陷。

三、外挂服务：Algolia、Meilisearch 这类#

把索引放到一台真的服务器上，查询走网络。

功能上限最高：分词器可换、同义词、拼写纠错、按字段加权、结果高亮、搜索分析——都能做。

代价也很清楚：

多了一个要运维的东西。 静态站的全部好处就是「没有服务器」，为了搜索把它加回来，这笔账要自己算
多了一个会挂的东西。 搜索服务挂了，站还在，但搜索框废了
多了一个花钱的地方。 免费额度通常按「记录数 × 查询次数」计

它适合「搜索是核心功能」的站点——文档站、电商、知识库。对个人博客，通常是过度配置。

怎么选#

文章数	建议	理由
< 50	第一种就够	全量 JSON 也就几百 KB，省一套索引流程
50 – 几千	第二种	索引与正文分离，零运维
搜索本身是产品	第三种	只有它能在分词这一层做文章

判断的关键不是功能表，是「索引存在哪」：在用户浏览器里、在构建产物里、还是在别人的服务器上。三种位置对应三种上限，没有例外。

顺带一句：搜索需要 JavaScript，这是要认的#

前两种方案都跑在浏览器里，所以没有 JS 就没有搜索。

这不是可以糊弄过去的——正确的做法是给一个 <noscript> 出口，让关掉 JS 的读者至少能走到归档页，而不是对着一个永远转圈的输入框。

参考#

Pagefind 官方文档（索引分片与多语言处理）
Fuse.js 官方文档（模糊匹配算法与阈值）
本文提到的中文召回限制来自本站在 2026-09 的实测：搜「排版」7 条命中，搜「行高」6 条命中，而搜「网页排版」只有 4 条——少掉的那几条正是正文里只写了「排版」、没写完整四个字的地方

复现方式：npm run build 之后到 /search/ 搜这三个词。 npm run dev 里搜不到任何东西——索引是构建期（Pagefind）生成的，开发服务器没有它。这个数字也会随内容增删而变化，上面记的是当时的快照。

构建可复现比你想的难，而且它值得

XIAOXUsop — Thu, 20 Nov 2025 00:00:00 GMT

「同一份源码应该构建出同一个产物」听起来像句废话。

但它在大多数项目里并不成立，而且失败方式全都极其安静：构建照常成功，产物照常能用，只是每次都不一样。

代价在后面才显现：你没法用 diff 判断「这次改动到底改了什么」，因为产物里全是无关噪声。

那些让构建不可复现的东西#

按我实际踩到的顺序：

一、时间戳。 最容易想到，也最容易修。但它的变体很多：产物里嵌构建时间、日志文件带时间、Date.now() 漏进某个 ID 的计算。

二、文件系统的枚举顺序。 目录里读文件不会保证顺序。你在本地按 A、B、C 遍历， CI 上可能是 C、A、B——于是拼接出的产物顺序不同。

修法是显式排序：

const files = await readdir(dir);
files.sort();   // 这一行不是可选的

三、哈希的输入里混进了路径。 哈希(绝对路径 + 内容) 会让产物随 checkout 目录变化。看起来低级，但在「把目录结构也算进去」时很容易顺手写出来。

四、依赖的解析顺序。 锁文件解决了一部分，但 ^1.2.3 这类范围在锁文件被删后仍会解析到不同版本。

五、当前时区。 这条最阴——见下文。

时区那条：一次真实的 CI 失败#

我给站点加了「定时发布」：frontmatter 里写 date，到点之前不发布。

实现很简单：比较文章日期与当前时刻。

本地全绿。推上去，CI 红了。

UTC+8 的机器：此刻是 9 月 12 日 01:57
CI（UTC）：  此刻是 9 月 11 日 17:57

new Date('2026-09-12') 在两种情况下都解析成 UTC 午夜，但「今天」取决于机器时区。于是同一篇文章在两地判定相反：本地认为该发布，CI 认为还没到点——而失败形态是「文章静默消失 → 引用它的 [[链接]] 变成断链」。

根子不在比较逻辑写错了，在于「是否发布」依赖了构建时刻。 只要依赖构建时刻，就必然破坏两件事：

构建可复现：9 月 11 日与 9 月 12 日构建出的产物不同
跨机器一致：作者本地能看到、CI 看不到，或反过来

我最后把这个功能删掉了。不是修不好，是代价算不过来： draft: true 已经覆盖了「还没写完」这个主要场景，而定时发布多出来的那点便利，换的是两个更重要的契约。

做不到的事不该留着。

怎么验#

「可复现」是个可以被证明的性质，不用靠信念。

最直接的做法：改变一个本不该影响内容的环境输入，再比哈希。仓库已经把这条做成命令：

npm run verify:reproducible

它会先扫描生产源码，禁止无参数 new Date() 与 Date.now() 直接读取构建时钟；再清空 .astro 与 dist，分别在 UTC 与 America/Los_Angeles 跑完整的 Astro + Pagefind，逐文件比较 SHA-256。当前 93 个产物跨时区逐字节一致；任一文件不同都会列出路径并以非零状态退出。

这里两层检查缺一不可：跨时区构建能抓出日期显示偏移，但抓不出一年才变化一次的页脚年份；源码时钟检查能在跨年之前就拦住后者。内容里的日期则统一按 UTC 日历显示，不会因为构建机位于负时区而退到前一天。

更有价值的一种是换一种无关输入再比。比如换行符：

# CRLF 工作区构建一次，LF 工作区构建一次，比对产物

我在这个站上做过这个实验：CRLF 与 LF 两种工作区，产物 sha256 完全一致 （87 个文件）。结论是换行符不影响产物——但这个结论是测出来的，不是想出来的。

为什么值得#

有人会说这是洁癖。不是。

可复现是「用 diff 做判断」的前提。 如果每次构建产物都在抖，那「这次提交改了什么」就只能靠读代码——而读代码是会漏的。

它也是缓存正确性的前提。构建产物不稳定，内容寻址的缓存就永远不命中，或者更糟：命中了不该命中的。

而代价通常很小。上面那些来源，每一个的修法都是几行：排序一下、固定一下、把时间从哈希输入里拿掉。

花的这几行，换来的是「diff 可信」。 这笔账很好算。

参考#

reproducible-builds.org（这个概念的系统性整理）
本站的实测：npm run verify:reproducible 会在两个时区完整构建并逐文件比对，同时禁止构建时钟泄漏；.gitattributes 统一换行符，内容层的排序全部显式化

此间札记

中文网页排版，多数主题都做错了

一、行高#

二、字重#

三、行宽#

四、中西文间距与标点#

五、一条容易漏的：中文没有斜体#

六、字体栈的顺序#

那要不要自托管中文字体#

小结#

参考#

这个博客是怎么搭的

你只需要改一个文件#

东西都在哪#

两种内容，两种组织方式#

用 [[方括号]] 连起来#

构建时会做体检#

给 AI 读者那一份#

部署#

详细说明#

你的博客该不该给 AI 一份 markdown

谁在要 markdown#

一个安静失败的实现细节#

为什么现成的工具都不太行#

难在哪#

两件必须做对的事#

顺带说一句 llms.txt#

参考文献#

静态站搜索的三种做法，以及它们各自真实的上限

一、放进浏览器：把内容全量打到前端#

二、放进构建产物：只下载倒排索引#

三、外挂服务：Algolia、Meilisearch 这类#

怎么选#

顺带一句：搜索需要 JavaScript，这是要认的#

参考#

构建可复现比你想的难，而且它值得

那些让构建不可复现的东西#

时区那条：一次真实的 CI 失败#

怎么验#

为什么值得#

参考#

用 `[[方括号]]` 连起来#