行内公式

质能方程 $E=m{c}^2$ 说明质量与能量等价；勾股定理写成 $a^2+b^2=c^2$。 行内公式夹在中文里时基线要对齐：这里的 $x_i$、${\sum }_{i=1}^n{x}_i$ 与 $\frac{a}{b}$ 都贴着汉字，行距不该被撑开。

上下标与根式：$f\left(x\right)=\sqrt[3]{x^2+1}$，希腊字母 $\alpha \beta \gamma \Delta \Omega$。

块级公式

用两个美元符号包住，独立成行，水平居中：

矩阵与分段函数：

另一种块级写法

也可以用 math 围栏，效果与美元符号一致：

公式里的中文

用 \text{} 包住中文，不必退回正文写法：

长公式

超宽的公式在窄屏上局部横向滚动，不撑破页面：

转义与写错

正文里要出现美元符号本身，用反斜杠转义：$100 与 $200 都是普通文本。

语法写错时只会标红那一处，不会让整页渲染失败：

配色是外衣，排版是骨架。骨架不对，穿什么都别扭。

先说不做什么

大部分「看起来还行但说不出哪里不对」的页面，问题通常很具体：

• 所有标题都比正文大 1.5 倍以上，层级靠字号硬堆
• 行距 1.5，但段落间距和行距一样，读起来像一大坨
• 每块内容都装了圆角卡片，视线找不到落点
• 用同一个灰色表达三种不同重要程度的信息

这些都不是审美问题，是信息结构没有翻译成视觉语言。

我的三个约束

接这个博客的时候，我给自己定了三条硬规则，逼自己不用简单的办法解决层级问题。

一、标题和正文同字号

字号不动，层级靠字重和空间。

有个细节值得说：中文正文字体（我用的是霞鹜文楷 Lite）通常只有 400 和 700 两档字重。如果 h2 和 h3 都用 700，在字号相同的前提下它们会长得一模一样。

我的解法是让 h3 用 400，但把颜色降到次级灰。层级用「更淡」表达，而不是「更粗」。

二、段落间距必须明显大于行距

行距 1.75 的时候，段落间距我用 1.2em。差值不大，但足够让眼睛知道"这里断开了"。

判断标准很简单：眯起眼睛看，段落应该像一块一块的，不是连续的一条。

三、用 1px 线，不用色块

border 比 background 精确得多。

.list-item {
  border-bottom: 1px solid var(--border);
  padding-block: 1rem;
}

.list-item:hover {
  /* 注意：不改背景色，只让标题变重 */
  font-weight: 700;
}

一行一条线，视线自然往下走。色块会把页面切碎，线不会。

一个反例

很多模板会这样处理元信息：

<span class="meta">2025-10-28 · 阅读 6 分钟 · 设计</span>

中间那个 · 看着挺简洁，但它没有传达任何信息，只是把三个不相干的东西粘在一起。

我改成：

<dl class="meta">
  <dd>2025-10-28</dd>
  <dt>6 min</dt>
</dl>

日期用等宽字体，时长用等宽字体，中间靠 1px 竖线或间距分开。等宽字体只给真实数据用——日期、字数、时长、代码。它不是装饰。

结果

同样的 zinc 灰阶，同样一个陶土色强调色，只调整字重、行距和分隔方式，页面的气质就从「模板」变成了「有人在排」。

在暗色模式下这一点尤其明显。因为我没有加任何阴影、没有玻璃拟态、没有渐变，暗色版本不是简单地把白底变黑底，而是重新配了一次权重关系：

// 暗色下强调色要提亮，否则在深色底上会糊成一团
const accent = {
  light: '#a94f33', // 对比度 5.45 on #fff
  dark: '#cc785c',  // 对比度 6.07 on #09090b
}

这两个值我实际算过 WCAG 对比度，不是拍脑袋定的。

最后

排版这件事的好处是：它不需要你有审美天赋，只需要你对信息结构诚实。什么重要，什么次要，什么是一组，什么该分开——想清楚了，视觉自然就出来了。

配色可以抄，排版抄不来，因为排版是判断题。

如果你的 RSS 阅读器能正常显示这一篇，说明转义是对的。

裸字符

下面这些字符在 XML 里都是危险的，必须转义：

• 与号：AT&T、Q&A、R&D
• 小于号：a < b
• 大于号：a > b
• 引号：他说 "这样" 和 '那样'
• CDATA 结束标记本身：]]>

如果不转义，AT&T 会把整个 feed 撑坏——因为解析器会以为 &A 是一个实体引用的开始。

代码块里的尖括号

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8" />
    <title>喵洛阁 &amp; 朋友</title>
  </head>
  <body>
    <p class="note">如果 a < b 并且 b > c，那么 a < c</p>
    <script>
      const html = '<div class="x">' + text + '</div>'
      if (a && b) console.log('&lt;ok&gt;')
    </script>
  </body>
</html>

上面这块 HTML 里 <、>、&、引号全都有。它在页面里应该原样显示，在 feed 里应该被正确转义。

再来一段 TypeScript：

// 这里的箭头函数、泛型尖括号、比较符号都不应该破坏 XML
type Predicate<T> = (value: T) => boolean

function filterAnd<T>(items: T[], pred: Predicate<T>): T[] {
  const out: T[] = []
  for (const item of items) {
    if (item && pred(item) && (out as unknown[]).length < 100) {
      out.push(item)
    }
  }
  return out
}

const flags = filterAnd([1, 2, 3], (n) => n > 1 && n < 3)
console.log('结果：', flags, '& 完成')

内联代码与引用

行内代码 const re = /<(\w+)>/g 里也有尖括号。

下面是一个引用块，里面同时含 HTML 和 shell：

试试 echo "<hello> & goodbye" 这条命令。

它会输出带尖括号和与号的字符串，而 shell 会尝试把它当成重定向或子命令。

表格

链接与图片

站内绝对链接：归档、标签、关于。

相对链接在 feed 里必须被改写成基于站点的绝对链接，否则阅读器里点不动。

图片同理：

一段长文本

Lorem ipsum 不如直接说清楚：这一段就是用来测行高和段距的。中文排版里，1.75 的行高配合 17px 的字号，一行大约能放下 44 个汉字，这个宽度在多数屏幕上读起来是舒服的。再宽一点，眼睛回行会累；再窄一点，一句话要折三次，节奏就散了。

段落间距必须明显大于行距。我用的是 1.2em——看起来差别不大，但眯眼一看就知道哪里断开了。如果段落间距等于行距，整页会糊成一块灰，读者找不到停顿点，读三行就想走。

结尾

如果这一篇在 reader 里结构完好、代码块没跑版、图片能加载、链接可点，那 feed 就是对的。

我每个月写两篇文章。

这两件事之间存在严重的不匹配。

先算笔账

我把访问数据拉出来看了看：

「其他所有页面」包括：分类索引、标签云、友链、关于、搜索页、404、两个我忘了当初为什么建的空页面。

它们加起来占了 3% 的流量，却占了我 70% 的维护时间。

删掉的清单

• 后台管理 —— 我用 Vim 写 markdown 比用任何后台都快
• 评论系统 —— 一年收到 4 条评论，其中 3 条是垃圾
• 访问统计的第三方脚本 —— 一个用了 8 年的静态博客，我不需要实时看板
• 搜索独立页 —— 搜索应该是弹窗，不该是一次页面跳转
• 分类页的独立布局 —— 它和标签页长得一模一样，为什么要写两遍
• 暗色模式的切换动画库 —— 我写了 40 行 clip-path 替代了它

保留的东西

删完之后剩下这些，一个都不能少：

/                 首页，最新文章列表
/posts/[slug]     文章
/archive          归档
/categories       分类
/tags             标签
/links            友链
/about            关于
/rss.xml          订阅

九个路由。其中三个（分类、标签、归档）共用同一个列表组件——它们本来就是同一个东西的不同切片。

性能是删出来的

改动前后，用 Lighthouse 在同一台机器上测：

没有做任何「优化」。没有拆包、没有预加载、没有 CDN 调优。

我只是不再发送用户不需要的代码。

// 删之前：每个页面都加载完整运行时
import { Analytics } from '@heavy/analytics'
import { Comments } from '@heavy/comments'
import { AdminWidget } from '@heavy/admin'

// 删之后：什么都没有
// 静态 HTML + 一个 3KB 的搜索索引（首次搜索才加载）

一个反直觉的发现

删功能最难的从来不是技术，是心理。

每删一个东西，我都会想：「万一以后要用呢？」

后来我给自己定了个规则：如果要重新加回来，成本低于 2 小时，那就先删掉。

后台管理？重写要 8 小时，不删。评论系统？接第三方要 20 分钟，删。搜索页？改成弹窗要 1 小时，删。

这条规则让我删掉了大约 60% 的东西，而没有任何一个功能被真的加回来过。

结论

一个博客的核心是：让人能读到文章。 其他一切都是配角。

我现在写一篇新文章的工作流是：新建一个 .md 文件，写 frontmatter，写正文，git push。

三十秒后它就在线上了，带 RSS、带搜索索引、带 OG 图。

这才是写博客该有的摩擦系数。

原因很简单——MiniSearch 默认的 tokenizer 按空格和标点切词。

对英文来说这没问题：

tokenize('hello wonderful world')
// ['hello', 'wonderful', 'world']

对中文来说这就是灾难：

tokenize('中文分词为什么把搜索做坏了')
// ['中文分词为什么把搜索做坏了']   ← 一整段算一个词

整段算一个词意味着：用户搜「分词」，匹配不上；搜「搜索」，也匹配不上。只有把整句原样打进去才可能命中。

三种切法

方案一：单字切分

tokenize('中文分词')
// ['中', '文', '分', '词']

召回率最高，因为任何两个字以上的词都包含单字。

但精度是灾难级的：搜「的」会命中所有文章；搜「一」几乎命中全站。搜索结果里全是噪音。

方案二：整词切分（需要词典）

用结巴之类的分词库，或者自己做词典最长匹配：

tokenize('中文分词为什么把搜索做坏了')
// ['中文', '分词', '为什么', '把', '搜索', '做', '坏', '了']

质量最好，但代价是：

• 要打包一份词典（几百 KB 到几 MB）
• 新词、专有名词、缩写经常分错
• 前端体积受不了

对一个 3KB 的搜索来说，这个方案太贵了。

方案三：bigram（我的选择）

每两个相邻字符算一个 token：

tokenize('中文分词')
// ['中文', '文分', '分词']

关键特性：任何长度 ≥ 2 的词，都必然包含它自己的完整 bigram。

• 「分词」→ 出现在 ['中文', '文分', '分词'] 里 ✓
• 「搜索」→ 出现在「把搜索做」的 bigram 里 ✓

所以用户输入一个词，就能匹配到包含它的句子，不需要词典。

为什么不直接用方案三

纯 bigram 有个缺口：单字查询召回为 0。

用户搜「猫」，没有 bigram 能匹配上「喵洛阁的猫」。

所以我的实现是 bigram 为主 + 单字兜底：

function tokenizeCJK(text: string): string[] {
  const tokens: string[] = []
  // 按非字母数字汉字切段
  const segments = text.split(/[^\p{L}\p{N}]+/u).filter(Boolean)

  for (const seg of segments) {
    const isCJK = /[\u4e00-\u9fa5]/.test(seg)

    if (!isCJK) {
      // 英文/数字：整词，转小写
      tokens.push(seg.toLowerCase())
      continue
    }

    const chars = [...seg]
    // bigram
    for (let i = 0; i < chars.length - 1; i++) {
      tokens.push(chars[i] + chars[i + 1])
    }
    // 单字兜底：短查询用
    for (const ch of chars) {
      tokens.push(ch)
    }
  }

  return tokens
}

单字会让索引变大一些、噪音多一点，但换来的是单字查询不会零结果。

权重比切词更重要

切对了之后还有个问题：搜「前端」，一篇标题叫《前端工程化》的和一篇正文里提到一次「前端」的，应该谁排前面？

MiniSearch 支持字段权重：

const miniSearch = new MiniSearch({
  fields: ['title', 'description', 'tags', 'category', 'text'],
  storeFields: ['title', 'path', 'date'],
  searchOptions: {
    boost: { title: 8, description: 4, tags: 3, category: 2, text: 1 },
    prefix: true,
    fuzzy: 0.2,
  },
  tokenize: tokenizeCJK,
})

标题权重 8 倍于正文。这样标题命中永远排在正文命中前面——这也正是验收标准要求的「标题命中权重最高」。

实测

改之前：

搜「前端」→ 0 结果
搜「分词」→ 0 结果

改之后：

搜「前端」→ 3 结果，第一条《我删掉了站点的 90% 功能》
搜「分词」→ 1 结果，第一条《中文分词为什么把搜索做坏了》
搜「猫」  → 1 结果，《关于这个博客》（正文提到「猫」）
搜「排版」→ 1 结果，《排版比配色更决定气质》

一句话总结

中文搜索的难点不在算法，在分词策略和你的用户输入习惯是否匹配。

bigram 不是最优解，但对一个没有后端、索引要压到 300KB 以内的静态博客来说，它是性价比最高的那个解。

用了半年之后我发现，它真正解决的问题根本不是"怎么动画"。

它解决的是什么问题

传统的页面转场动画难写，不是因为 CSS 难，而是因为你要同时管理两个状态。

从列表页跳到详情页，你得：

1. 给旧页面加一个 "leaving" 类
2. 等动画结束
3. 卸载旧页面
4. 挂载新页面
5. 给新页面加一个 "entering" 类
6. 再等动画结束

六个步骤，任何一步时序错一点就会闪。

View Transitions 把这六步变成了一个 API：

document.startViewTransition(() => {
  // 只在这里改 DOM，浏览器负责前后的快照和过渡
  renderNewPage()
})

浏览器会：对旧状态截图 → 执行你的回调 → 对新状态截图 → 在两帧之间做过渡。

你只描述"变成什么样"，不描述"怎么变"。

三种实际用法

一、页面切换

Nuxt 开了 experimental.viewTransition 之后，页面过渡可以完全用 CSS 控制：

::view-transition-old(root) {
  animation: 200ms ease-out both fade-out;
}

::view-transition-new(root) {
  animation: 200ms ease-out both fade-in;
}

@keyframes fade-out {
  to { opacity: 0; }
}

@keyframes fade-in {
  from {
    opacity: 0;
    transform: translateY(4px);
  }
}

注意这里没有 JS。转场逻辑全在 CSS 里，JS 只负责换内容。

二、主题切换的圆形扩散

这个效果很多人以为是手写 clip-path 加 requestAnimationFrame，其实可以完全交给 View Transitions：

async function toggleTheme(x: number, y: number) {
  const radius = Math.hypot(
    Math.max(x, innerWidth - x),
    Math.max(y, innerHeight - y),
  )

  const transition = document.startViewTransition(() => {
    document.documentElement.classList.toggle('dark')
  })

  await transition.ready

  document.documentElement.animate(
    {
      clipPath: [
        `circle(0px at ${x}px ${y}px)`,
        `circle(${radius}px at ${x}px ${y}px)`,
      ],
    },
    {
      duration: 200,
      easing: 'ease-out',
      pseudoElement: '::view-transition-new(root)',
    },
  )
}

关键在 pseudoElement: '::view-transition-new(root)'——你不是在动画真实 DOM，是在动画浏览器的过渡快照层。所以这个动画不会触发重排。

三、列表到详情的共享元素

给元素一个 view-transition-name：

.post-card__title { view-transition-name: post-title; }
.post-detail__title { view-transition-name: post-title; }

两个页面上同名，浏览器就会把它们当成同一个元素，自动做位置和尺寸的插值。

::view-transition-old(post-title),
::view-transition-new(post-title) {
  animation-duration: 250ms;
  animation-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
}

必须知道的三个限制

一、同一时间只能有一个 view-transition-name 在页面上。

如果列表里有 10 张卡片都叫 post-title，浏览器会直接报错、整个过渡失效。所以列表页通常不给每张卡单独命名，只在用户点击时动态设置。

二、动画期间页面不可交互。

过渡快照覆盖在真实 DOM 之上。所以别做超过 300ms 的转场。

三、必须尊重 prefers-reduced-motion。

const reduceMotion = matchMedia('(prefers-reduced-motion: reduce)').matches
const supported = 'startViewTransition' in document

if (!supported || reduceMotion) {
  // 直接切，不做动画
  applyChange()
  return
}

这不是可选项。前庭功能障碍的用户会因为这种动画头晕。

什么时候不该用

• 表单提交后的状态更新 —— 不需要转场，用户只想知道成功了没
• 列表项的 hover 效果 —— 那是微交互，用 transition 就够了
• 超过 300ms 的复杂编排 —— 会让人等

View Transitions 的定位是页面级的状态切换，不是"万能动画方案"。

一句话

它把"两套状态之间怎么过渡"这件麻烦事，从你手里拿走了。

这可能不是最酷的动画 API，但它是我用过最省心的那个。

1. Algolia（要付费、要联网、要等索引同步）
2. MeiliSearch（要跑一个服务）
3. Pagefind（好，但更偏向几千页以上的站）
4. 搜索引擎的 site: 语法（等于没有）

我用的是第五种：构建时生成一个 JSON 索引，前端按需加载。

索引长什么样

[
  {
    "id": "typography-over-color",
    "title": "排版比配色更决定气质",
    "description": "把同样一套颜色交给两个人排，出来的东西可以完全不同。",
    "tags": ["排版", "设计", "CSS"],
    "category": "设计",
    "text": "做前端这些年我逐渐发现一个规律换一套配色页面会变好看改一遍排版页面会变成另一个东西…",
    "path": "/posts/typography-over-color",
    "date": "2025-10-28T00:00:00.000Z"
  }
]

就这些字段，一个都不多。

为什么这么小

假设你有 100 篇文章，每篇 3000 字。

• 原始 markdown：100 × 3000 × 3 bytes ≈ 900 KB
• HTML 渲染后：大约 2.5 MB（标签很占地方）
• 剥离 HTML 后的纯文本：约 850 KB
• gzip 之后：约 180 KB

关键动作是剥 HTML。这一步能砍掉 60% 以上。

function stripHtml(html: string): string {
  return html
    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
    .replace(/<pre[\s\S]*?<\/pre>/gi, ' ')   // 代码块也剥掉
    .replace(/<[^>]+>/g, ' ')
    .replace(/\s+/g, ' ')
    .trim()
}

那行 <pre> 的处理是有争议的。代码块里全是 useState、div、const 这种标识符，进索引只会制造噪音——用户搜「前端」不该命中一个满是 div 的代码块。

什么时候加载

用户第一次打开搜索框的时候。

不是页面加载时，不是空闲时，是真正按下 Ctrl+K 的那一刻。

let indexPromise: Promise<MiniSearch> | null = null

function ensureIndex() {
  if (!indexPromise) {
    indexPromise = fetch('/api/search-index.json')
      .then((r) => r.json())
      .then((docs) => {
        const ms = new MiniSearch({ /* ... */ })
        ms.addAll(docs)
        return ms
      })
  }
  return indexPromise
}

用一个 Promise 做缓存的好处是：连续按三次 Ctrl+K 也只会发一次请求。

加载要多久

本地测：180KB 的 JSON，fetch + JSON.parse + addAll 建索引，大约 60~90ms。

用户感知不到。但如果索引超过 500KB，这个数字会变成 300ms+，就该考虑分片或者换 Pagefind 了。

所以我的判断线是：索引 gzip 后 300KB 以内用方案五，超过就用 Pagefind。

对一个个人博客（几十到几百篇）来说，永远到不了这条线。

不用后端的三个好处

一、离线可用。 Service Worker 缓存了索引之后，断网也能搜。

二、零延迟。 没有网络往返，搜索是同步的（建完索引之后）。

三、部署即生效。 写文章 → git push → 构建 → 索引和文章一起上线。不需要"等 Algolia 爬"。

唯一的问题

索引是构建时生成的，所以：

草稿不会被搜到。 这是对的。

但新文章要重新构建才能搜到。 对静态博客来说这本来就是事实——文章本身也要重新构建才存在。

所以这个"缺点"根本不存在。

结语

技术选型的本质是匹配规模。

Algolia 对一万篇文章的电商站是对的；MeiliSearch 对需要实时索引的社区是对的；一个 JSON 文件对个人博客是对的。

用大炮打蚊子不叫稳健，叫没算清楚。

• 白色背景
• 每块内容一个圆角 16px 的卡片
• 卡片下面一层 0 4px 6px rgba(0,0,0,.1) 的阴影
• 卡片之间 24px 间距
• 所有卡片长得一模一样

这个布局不算丑，但它有一个致命问题：读者不知道先看哪里。

卡片传递的错误信息

在视觉语言里，一个边界明确的容器在说：「这是一组相关的东西，和外面无关。」

这是有用的信息——但前提是并非所有东西都是卡片。

如果 10 块内容全都是卡片，那这个信号就失效了。就像一篇文章里每个词都加粗，等于没加粗。

具体到博客：

我用什么代替

列表：横线 + 间距

.post-list {
  display: flex;
  flex-direction: column;
}

.post-item {
  display: flex;
  align-items: baseline;
  gap: 1rem;
  padding-block: 0.875rem;
  border-bottom: 1px solid var(--border);
}

.post-item:last-child {
  border-bottom: none;
}

一行一条线。视线沿着线往下走，不会被框住。

而且 border 比 box-shadow 便宜得多——阴影会触发重绘，边框不会。

分组：留白

不需要任何视觉元素，间距本身就是分组。

.section {
  margin-block-start: 3rem;
}

.section + .section {
  margin-block-start: 4rem;
}

大间距说「这是新的部分」，小间距说「这些是一起的」。这是人类视觉系统最古老的规则之一，不需要额外的框。

强调：字重和颜色

想突出某一块内容，不要给它加边框，改它的字重。

.post-item:hover .post-item__title {
  font-weight: 700;
}

从 400 到 700 的变化，比任何阴影都醒目，而且不占空间、不增加视觉噪音。

那卡片什么时候用

三个条件同时满足才用：

1. 内容确实是独立的、可以单独存在的单元
2. 它需要和周围的内容明确区分开
3. 数量不多（少于 10 个）

友链页的每个友链符合这三条——它们确实彼此无关，确实需要区分，数量也不多。

文章列表不符合第一条：10 篇文章是一个连续的序列，不是 10 个独立单元。

一个具体的对比

同一个博客，两种列表：

卡片式：

┌─────────────────────────┐
│ ┌─────────────────────┐ │
│ │ 排版比配色更决定气质 │ │
│ │ 2025-10-28          │ │
│ └─────────────────────┘ │
│ ┌─────────────────────┐ │
│ │ 我删掉了站点的 90%   │ │
│ │ 2025-10-12          │ │
│ └─────────────────────┘ │
└─────────────────────────┘

行式：

2025-10-28   排版比配色更决定气质
──────────────────────────────────
2025-10-12   我删掉了站点的 90% 功能
──────────────────────────────────

行式版本：

• 纵向高度减少约 50%，一屏能看更多文章
• 日期对齐成一列，可以扫读
• 视线路径是单一的从上到下
• 没有任何装饰性的视觉重量

最后

卡片不是设计元素，是信息结构的可视化。

当你不知道该怎么组织内容时，把东西装进卡片是最省事的选择——但也是最偷懒的选择。

真正该问的问题是：这些内容之间是什么关系？

是序列？用列表。 是并列的独立实体？用网格或卡片。 是从属关系？用缩进。 没有关系？用留白隔开。

想清楚关系，视觉自然就对了。

一套完整的霞鹜文楷，woff2 格式大约 20-25 MB。用户打开首页就要下载这个？显然不行。

所以大部分中文站的选择是：用系统字体。然后全站看起来就像一张没洗过的 PPT。

分片是怎么解决的

关键洞察：一篇文章不可能用到所有汉字。

常用的 3500 个汉字覆盖了 99.5% 的日常文本。剩下几万个字可能一辈子都不会出现在我的博客里。

所以现代中文字体包的做法是：

1. 按 Unicode 范围把字体切成几百个小文件
2. 每个文件用 unicode-range 声明自己负责哪些码位
3. 浏览器只下载页面实际用到的那些分片

/* 分片 #12 负责这些码位 */
@font-face {
  font-family: 'LXGW WenKai Lite';
  font-weight: 400;
  font-display: swap;
  src: url('./files/subset-12.woff2') format('woff2');
  unicode-range: U+4E00-4E1F, U+4E30-4E4F;
}

浏览器渲染一段文字时，会先检查每个字符属于哪个 unicode-range，只下载覆盖到的分片。

实际数字

我这个博客用 lxgw-wenkai-lite-webfont：

25MB 的包，实际只用了 180KB。

font-display: swap 的必要性

@font-face {
  font-display: swap;
}

swap 的意思是：先用后备字体渲染，字体加载完再换。

代价是会看到一次字体闪烁（FOIT → FOUT）。收益是文字永远可读。

另外两个选项都不适合中文：

• block：字体没加载完就不显示文字。中文 180KB 可能要 500ms，用户会看到一片空白
• optional：网络慢就永远不用自定义字体。会导致同一篇文章有时是文楷有时是黑体

swap 是唯一合理的选项。

后备字体链要写对

font-family:
  'Inter Variable',
  'LXGW WenKai Lite',
  'PingFang SC',
  'Microsoft YaHei',
  sans-serif;

这个链的顺序有讲究：

1. Inter 负责拉丁字母和数字 —— 它的西文比文楷好看得多
2. 文楷 负责汉字 —— 在 Inter 没有对应字形时接管
3. 苹方 / 微软雅黑 —— 文楷分片还没加载完时的后备
4. sans-serif —— 最后兜底

关键在于第 1 和第 2 的顺序：浏览器是逐字符查找的。英文字符在 Inter 里能找到，就不会去问文楷；汉字在 Inter 里找不到，自然落到文楷。

这样西文和中文各用各的最优字体，不需要任何 unicode-range 技巧。

等宽字体只给数据

font-family: 'JetBrains Mono', 'LXGW WenKai Lite', ui-monospace, monospace;

等宽字体我用在四个地方，只有四个：

• 日期（2025-10-28）
• 阅读时长（6 min）
• 代码块
• kbd 元素

不用它做装饰性的小标签。 那些 MONOSPACE 风格的 eyebrow 文本是模板化的标志之一——它看起来"有技术感"，但没传达任何信息。

一个坑

字体分片依赖 unicode-range，而 unicode-range 是静态声明的。

意思是：如果你的文章里出现了某个生僻字，而那个字所在的分片没有被任何 @font-face 覆盖（有些字体包会漏掉扩展区），那个字就会掉到后备字体。

结果是一篇文章里 99% 是文楷，中间蹦出一个黑体的字。

我的处理是接受它——比为了一个字加载一整个 3MB 的扩展区划算得多。

结论

中文字体不是"能不能自托管"的问题，是"有没有做分片"的问题。

用了分片之后：

• 首屏字体成本 ≈ 180KB（可接受）
• 视觉一致性 100%（全站统一字体）
• 零第三方请求（隐私友好，也不受 CDN 挂掉影响）

这套方案我已经跑了一年，没有换回去的理由。

/* 这就是全部实现 */
.dark {
  filter: invert(1) hue-rotate(180deg);
}

或者稍微认真一点的：

.dark {
  --bg: #000;
  --text: #fff;
}

两种都错。

为什么不能简单反转

一、纯黑配纯白太刺眼

白底黑字的对比度是 21:1，这是物理极限。

在亮环境下这没问题——瞳孔小，进光量少。但在暗环境下，你的瞳孔放大了，屏幕成了唯一光源，21:1 的对比度会让眼睛很快疲劳。

所以暗色模式的标准做法是：

.dark {
  --background: #09090b;  /* 不是 #000 */
  --foreground: #fafafa;  /* 不是 #fff */
}

对比度降到约 19:1。差别不大，但长时间阅读舒服很多。

二、纯黑背景会让阴影失效

亮色模式下阴影是黑色半透明：

box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);

暗色模式下把同一个阴影放在 #09090b 上——你什么都看不见。黑色叠黑色。

这就是为什么暗色模式通常完全禁用阴影，改用边框或者亮度差来区分层级：

.dark * {
  box-shadow: none;
}

/* 用亮一点的面表达"浮起来" */
.dark {
  --surface: #18181b;      /* 页面底 #09090b，卡片 #18181b */
  --surface-hover: #27272a;
}

三、强调色必须重新调

同一个颜色在亮底和暗底上的感知完全不同。

我的强调色：

如果暗色模式还用 #a94f33，它在深色底上会显得脏——像褪色的油漆。因为深色底会让低亮度颜色失去光泽。

反过来，如果亮色模式用 #cc785c，在白色上对比度只有 3.1:1，达不到 WCAG AA 的 4.5:1。

所以强调色必须有两套值，这不是可选项。

完整的变量对照

:root {
  --background: #ffffff;
  --foreground: #18181b;
  --muted: #fafafa;
  --muted-foreground: #71717a;
  --border: #e4e4e7;
  --accent: #a94f33;
}

.dark {
  --background: #09090b;
  --foreground: #fafafa;
  --muted: #18181b;
  --muted-foreground: #a1a1aa;
  --border: #27272a;
  --accent: #cc785c;
}

注意 --muted-foreground 的变化：

• 亮色：#71717a，比正文浅，但仍能读
• 暗色：#a1a1aa，比正文暗，但仍能读

方向是反的，但目的相同：比正文低一级，但保持可读。

如果暗色模式直接用亮色模式的 #71717a，它在 #09090b 上的对比度只有 4.3:1——刚好在 AA 线下面。

三态切换而不是两态

只用两态（亮/暗）有个问题：用户系统里设了「跟随时间自动切换」，但网站不认。

所以我的实现是三态：

type ThemeMode = 'light' | 'dark' | 'system'

system 模式下监听 prefers-color-scheme：

const mq = matchMedia('(prefers-color-scheme: dark)')

mq.addEventListener('change', () => {
  if (mode.value === 'system') {
    applyTheme(mq.matches)
  }
})

这样用户在系统里切了主题，网站立刻跟上，不需要手动点。

防止闪烁（FOUC）

最烦人的 bug：页面先渲染成亮色，200ms 后闪成暗色。

原因是 CSS 变量在 JS 执行后才生效。解法是在 <head> 里插一段同步执行的脚本：

<script>
  (function () {
    try {
      var m = localStorage.getItem('theme-mode')
      var d = m === 'dark' || ((!m || m === 'system') &&
        window.matchMedia('(prefers-color-scheme: dark)').matches)
      document.documentElement.classList.toggle('dark', d)
    } catch (e) {}
  })()
</script>

关键点：

• 必须是内联的（外部脚本要等网络）
• 必须同步（defer/async 都会晚）
• 必须在 <head> 里（<body> 末尾太晚）
• 必须包 try/catch（隐私模式下 localStorage 会抛异常）

一句话

暗色模式是第二套设计，不是第一套的滤镜。

它需要独立的对比度核算、独立的阴影策略、独立的强调色。省掉这些步骤，出来的东西就是"能看但难受"。

毕竟写死一个站名能出什么问题？改的时候全局替换一下不就完了。

我做这个博客的时候，把这条规则当成了硬性架构约束。半年后的结论是：它带来的收益远超预期，而且和代码整洁没什么关系。

四层配置

我把所有可变内容分成四层：

app/blog.config.ts     站点身份、feed、search
app/theme.config.ts    设计 token（颜色、字号、间距、圆角、动效）
app/pages.config.ts    逐路由的业务参数
app/data/*.ts          友链、关于页元数据、系统文案

组件里一行硬编码都不许有。

<!-- 禁止 -->
<h1>喵洛阁</h1>
<a href="https://github.com/kemiaosw">GitHub</a>

<!-- 允许 -->
<h1>{{ site.name }}</h1>
<a :href="social.url">{{ social.label }}</a>

收益一：改一处，全站同步

最直接的收益是这个。举个真实例子：我想把「归档」改成「时间线」。

// 改这一行
nav: [
  { label: '时间线', to: '/archive', icon: 'tabler:archive' },
]

改完，桌面导航、平板汉堡菜单、移动端底部 Tab 栏，三处同时更新。

如果这些 label 是硬编码在三处的，我至少要改三个文件，而且很可能漏掉移动端（因为它在另一个组件里，平时不怎么看）。

收益二：配置即文档

打开 blog.config.ts，你立刻知道这个站有哪些页面、有哪些社交链接、RSS 开没开。

export default defineAppConfig({
  site: {
    name: '喵洛阁',
    nav: [
      { label: '首页', to: '/', icon: 'tabler:home' },
      { label: '归档', to: '/archive', icon: 'tabler:archive' },
      // ...
    ],
  },
})

这比翻 15 个 .vue 文件去找 to="/archive" 快得多。

收益三：功能开关变成真的开关

这是我最没想到的收益。

提示词的验收标准里有一条：

feed / search 任一 enabled: false 后：入口消失、对应路由 404、head 无相关注入

如果没有配置层，这个需求要改 6 个地方：

1. 删掉 footer 的 RSS 链接
2. 删掉 <head> 的 <link rel="alternate">
3. 删掉 server/routes/rss.xml.get.ts
4. 改 nitro.prerender.routes
5. 删掉搜索按钮
6. 解绑快捷键

有了配置层，它们全都读同一个字段：

const { feed, search } = useSiteConfig()

// footer
<NuxtLink v-if="feed.rss.enabled" :to="feed.rss.path">RSS</NuxtLink>

// head
if (feed.rss.enabled) links.push({ rel: 'alternate', ... })

// 路由
if (!feed.rss.enabled) throw createError({ statusCode: 404 })

开关的原子性从"靠人记得改全"变成了"结构上不可能不同步"。

收益四：主题切换不用碰组件

设计 token 全在 theme.config.ts：

theme: {
  accent: { light: '#a94f33', dark: '#cc785c' },
  radius: '0.5rem',
  contentMaxWidth: '764px',
  animation: { duration: 200, easing: 'ease-out' },
}

这些值在构建期被编译成 CSS 变量：

:root {
  --accent: #a94f33;
  --radius: 0.5rem;
  --content-max-width: 764px;
  --duration-base: 200ms;
}

组件里只写 var(--accent)，不写 hex。

想换强调色？改两行。想换字体？改 fontFamily。想让动画慢一点？改 duration。

不需要在 30 个 .vue 文件里搜索替换。

代价是什么

诚实地说，这套架构有成本：

一、多一层间接。 看 {{ site.name }} 不如看 喵洛阁 直观。新人接手要先去读配置文件。

二、类型定义要维护。 useSiteConfig() 里的 interface 得和 blog.config.ts 保持同步。

三、过度抽象的风险。 如果某个值只在一个组件里用一次，且永远不会变，那抽到配置层就是浪费。

我的判断标准是：如果一个值有 ≥ 2 个使用点，或者有「未来可能改」的可能，就抽出来。否则就地写死。

比如「回到首页」这个按钮的文案——它在 404 页和错误页都用，所以放进了 app/data/system.ts。

而 aria-hidden="true" 这种纯技术属性，就地写，不进配置。

怎么验证没漏

验收标准里有一条：grep -r "硬编码字符串" app/components app/pages 命中为 0。

我实际跑的命令是：

# 找中文字符串（排除注释和 CSS）
grep -rn '[\u4e00-\u9fa5]' app/components app/pages \
  --include='*.vue' | grep -v '^\s*\*' | grep -v '<!--'

第一次跑出来 47 处，其中 41 处是真硬编码，6 处是误报（CSS 注释里的说明文字）。

改完之后是 0。

结论

零硬编码不是为了"代码漂亮"，是为了让配置变更具备原子性。

一个改了会漏的地方，早晚会漏。一个结构上不可能漏的地方，永远不漏。

这就是架构和整洁的区别。

于是换编辑器：Sublime → VS Code → Obsidian → Typora → 又回到 VS Code。

换笔记系统：印象笔记 → Notion → Roam → Logseq → 纯 markdown 文件夹。

换写作方法：卡片笔记法、Zettelkasten、番茄钟、晨间日记。

三年过去，公开发布的文章：4 篇。

转折点

去年年底我清电脑，翻到一个 2019 年的文件夹，里面躺着 37 个 .md 文件。

标题都是这样的：

• 关于性能优化的一些想法.md
• 重构的时机.md
• 为什么我不喜欢 TypeScript.md

每个文件打开都是 200 字左右，写到一半停住。

那 200 字都不差。它们没写完的原因不是写得不好，是我在写的过程中不断问自己：

这篇有价值吗？别人会不会觉得太浅？这个观点是不是早就有人写过？

然后我就去搜，去对比，去补充，去重写开头。

一篇文章的写作时间，80% 花在自我怀疑上。

我改了什么

不是换了工具，是换了标准。

以前的标准：这篇文章要提供新的、完整的、正确的见解。

现在的标准：这篇文章要让我自己三个月后还能看懂我当时在想什么。

这个转变带来的直接后果是：不再追求全面。

一篇讲「暗色模式」的文章，我不再试图覆盖所有情况（品牌色怎么办、图片怎么处理、打印样式怎么办）。我只写我自己踩过的那三个坑。

不完整，但真实。

具体做法

一、先写正文，最后写标题

标题是最容易卡住的地方，因为它要同时满足"准确"和"吸引人"。

所以我现在先写正文，写完再回头看这篇到底在说什么，标题自然就有了。

有时候标题会变成一句正文里的话。

二、允许文章短

我有一篇只有 400 字。它讲了一个很小的 CSS 技巧。

如果按以前的标准，这个长度不值得发。现在我觉得：如果这 400 字能省下别人 20 分钟试错，它就值得存在。

三、不修改超过两遍

第一遍写完，放一天，第二遍通读改错别字和逻辑断层。

然后发。

不再有第三遍。 第三遍开始就是自我怀疑的循环了。

四、公开发布，而不是攒着

攒稿的诱惑很大：「等我攒够十篇再一起发，显得专业一点。」

但攒稿的结果通常是：攒到第三篇就停了，因为看不到反馈。

发出去之后，哪怕只有一个人读，那种"有人看了"的感觉会推着写下一篇。

现在的状态

从去年年底到现在，8 个月，写了 23 篇。

没有一篇是"完美"的。有几篇我现在回头看觉得观点太幼稚。有一篇甚至有个技术错误（后来在评论区被指出来了）。

但 23 篇 > 4 篇。

而且我发现一件有意思的事：写得越多，写得越快。

第一篇花了三个周末。最近一篇花了一个晚上。

不是因为变厉害了，是因为不再为"写得不够好"而停下来。

一句话

写作的敌人不是没灵感，是完美主义。

完美主义让你在第一个段落就反复推敲，然后永远到不了第二段。

放弃完美，先写完，再改。这是唯一有效的方法。

1. 底部有没有 Tab 栏
2. 主题切换按钮在不在拇指够得着的地方
3. 环境光暗的时候，界面有没有做适配

为什么是底部 Tab 栏

单手握持手机时，拇指的自然活动范围是一个以屏幕下缘为圆心的扇形。

屏幕顶部 1/3 是拇指的「不可达区」。把导航放那里，意味着用户要换手或者用另一只手。

所以 iOS 和 Android 的主流 App 全都把一级导航放底部。Web 应用也应该这样。

我的做法：

桌面 ≥1024px    顶部水平导航
平板 768-1023   汉堡菜单
移动 <768px     底部固定 Tab 栏（4-5 格）

移动端底栏的 5 格是：首页 / 归档 / 分类 / 标签 + 搜索。

安全区：被忽略的 iPhone 细节

全面屏手机底部有一条系统手势条（Home Indicator）。

如果你的固定底栏紧贴屏幕底缘，手势条会压在它上面：

/* 错误 */
.tabbar {
  position: fixed;
  bottom: 0;
}

/* 正确 */
.tabbar {
  position: fixed;
  bottom: 0;
  padding-bottom: env(safe-area-inset-bottom, 0);
}

env(safe-area-inset-bottom) 在 iPhone 上是 34px，在没有手势条的设备上是 0。

一行 CSS，避免手势条盖住「搜索」按钮。

375px 下的正文排版

我的正文容器在桌面是 764px，移动端自然是 100% 减去左右 padding。

字号不能缩。

很多人在移动端把正文从 17px 缩到 15px，理由是"屏幕小"。

这是反的：屏幕越小，眼睛离屏幕越近，但单行字数也越少。缩字号会让行更短、折行更多，读起来更累。

正确的移动端排版：

• 字号不变（17px）
• 行高不变（1.75）
• padding 收窄（24px → 20px）
• 代码块允许横向滚动（不要折行）

图片的移动端处理

全宽图片在小屏幕上没问题，但要注意两点：

一、高度别用 vh 定死。 手机竖屏的 vh 包含地址栏高度，会跳。

二、懒加载是必须的。 文章第三屏往后的图片，用户可能永远不会滚到。

<img loading="lazy" decoding="async" ... />

decoding="async" 让图片解码不阻塞主线程，和 lazy 是两个维度的事，都要写。

断点的哲学

我用的断点很少：

< 768px      移动
768-1023px   平板
≥ 1024px     桌面
≥ 1280px     桌面 + 目录旁栏

只有四个，因为断点应该对应真实的设备形态，而不是随便划几刀。

平板为什么用汉堡菜单？因为 768-1023px 宽度下，水平导航 + 正文 764px 会挤，但底栏又显得空间浪费。汉堡菜单是这个形态下的正确答案。

触控目标

所有可点击元素的触控目标至少 44×44px（iOS HIG 的标准）。

我的搜索按钮是 32×32px 的图标，但外层有 16px 的点击热区扩展：

.search-trigger {
  width: 32px;
  height: 32px;
  position: relative;
}

.search-trigger::after {
  content: '';
  position: absolute;
  inset: -8px;
}

视觉小，触控大。这是图标按钮的标准做法。

一句话

移动端适配不是"能用"，是单手、通勤、暗光下都不难受。

做到这三点，就已经超过 80% 的网站了。

方案 A：点击链接后，页面白屏 300ms，然后新页面完整出现。

方案 B：点击链接后，立刻显示骨架屏，800ms 后内容填进来。

哪个更快？A。

哪个感觉更快？A。

骨架屏不是为了让页面"看起来在加载"，它是在承认"我在加载"。而这个承认本身，就是一种延迟信号。

真正的「无加载」是什么

无加载的意思是：用户从未看到"等待"这个状态。

实现它需要三个条件同时成立：

1. 页面在点击之前就已经准备好了
2. 切换过程不出现空白帧
3. 没有任何 loading 指示器

条件一：提前准备

SSG（静态生成）把这件事做到了极致：所有页面在构建时就变成了 HTML 文件。

点击链接时，浏览器请求的是一个已经存在的静态文件——不是"等服务器查询数据库再渲染"。

但即使如此，仍然有一次网络往返。所以还需要预取：

<!-- Nuxt 的 NuxtLink 默认开启 prefetch -->
<NuxtLink to="/archive">归档</NuxtLink>

Nuxt 会在链接进入视口时预取目标页面的 payload。用户真正点击时，数据已经在内存里了。

关键细节：外链和友链要显式关闭预取，否则会预取一堆无关域名。

<NuxtLink to="/links" no-prefetch>友链</NuxtLink>

条件二：不出现空白帧

即使数据准备好了，页面切换仍然会有一次 DOM 重建。

如果没有过渡，你会看到：旧页面消失 → 空白 → 新页面出现。

那"空白"可能只有 16ms（一帧），但眼睛能看见。

解法是 out-in 模式的页面过渡：

// nuxt.config.ts
app: {
  pageTransition: { name: 'page', mode: 'out-in' },
}

.page-enter-active,
.page-leave-active {
  transition: opacity 200ms ease-out, transform 200ms ease-out;
}

.page-enter-from {
  opacity: 0;
  transform: translateY(4px);
}

.page-leave-to {
  opacity: 0;
}

200ms 的淡入淡出。旧页面淡出的同时新页面淡入，中间没有空白帧。

为什么是 200ms？ 低于 150ms 感知不到，高于 300ms 开始觉得慢。200ms 是"有过渡但不等待"的窗口。

条件三：删掉 loading 指示器

这一条最反直觉。

大部分项目会加一个顶部进度条（NuxtLoadingIndicator）：

<!-- 删掉这个 -->
<NuxtLoadingIndicator />

进度条的存在本身就在告诉用户："可能要等一下"。

当你的页面跳转真的在 200ms 内完成时，进度条会闪一下——比没有更糟。

所以我把 NuxtLoadingIndicator 完全删掉了，靠 view transition 自然过渡。

一个真实的对比

改之前（有骨架屏 + 进度条）：

点击 → 进度条出现 → 骨架屏 → 内容填入 → 进度条消失
总时长：约 600ms，用户全程在"等待"

改之后（SSG + 预取 + 过渡）：

点击 → 淡出 → 淡入
总时长：约 200ms，用户感知为"瞬间"

什么情况下做不到

诚实地说，这套方案有三个前提：

一、内容必须是静态的。 如果页面需要实时数据（股票、聊天），SSG 帮不上忙。

二、页面数量要可控。 全量预渲染 10 万个页面，构建要几小时。

三、首屏没法这样优化。 用户第一次访问仍然要下载 HTML + CSS + JS。这是物理限制。

对一个个人博客来说，这三个前提全都成立——所以它能做到真正的无加载。

首屏怎么办

首屏的唯一优化方向是减小体积。

我的做法：

• 没有第三方脚本（统计默认关闭）
• 字体分片，实际加载约 180KB
• 搜索索引懒加载（首次搜索才请求）
• 零运行时状态库（没有 Pinia）

结果：首屏 JS 约 41KB（gzip 后）。

一句话

无加载不是把加载藏起来，是让加载根本不需要发生。

这两者的区别在于：前者是障眼法，后者是架构。

你可以写一份完美的 tokens.css，但只要有人在某个组件里写了 style="margin-top: 24px"，系统就开始腐烂了。

我的做法：让 token 只有一个来源

app/theme.config.ts   ← 唯一的真相源（TypeScript 对象）
        ↓ 构建期编译
tokens.generated.css  ← 自动生成，不手改
        ↓
组件里的 var(--accent)  ← 只读变量

关键在中间那一步：CSS 不是手写的，是生成的。

// modules/design-tokens.ts（简化）
const theme = await import('../app/theme.config.ts')

const css = `
:root {
  --accent: ${theme.accent.light};
  --background: ${theme.neutral.light.background};
  --content-max-width: ${theme.contentMaxWidth};
  --duration-base: ${theme.animation.duration}ms;
}

.dark {
  --accent: ${theme.accent.dark};
  --background: ${theme.neutral.dark.background};
}
`

这样如果有人想改强调色，他只能去改 theme.config.ts——因为 CSS 文件里改的东西下次构建就没了。

一个必须解决的坑

Tailwind v4 用 @theme 块定义工具类：

@theme {
  --color-accent: #a94f33;
}

这会生成 bg-accent、text-accent 等工具类。

但如果你把 hex 直接写进去，暗色模式就失效了——因为 --color-accent 被编译进了工具类，.dark 里覆盖 --accent 不会影响它。

正确做法是让 @theme 指向动态变量：

@theme {
  --color-accent: var(--accent);  /* 不是 hex */
}

:root { --accent: #a94f33; }
.dark { --accent: #cc785c; }

这样 bg-accent 编译出的 CSS 是 background-color: var(--accent)，会跟随主题切换。

我第一次写的时候踩了这个坑，暗色模式下所有强调色都不变，排查了半小时。

静态 token 和动态 token 要分开

不是所有 token 都需要跟随主题切换。

把字号也放进 .dark 里是浪费——它不会变，重复声明只会让 CSS 变长。

为什么不用 CSS-in-JS

有人会问：为什么不直接在 JS 里算好样式？

三个理由：

一、SSR 友好。 CSS 变量在 HTML 里就能生效，不需要等 JS 执行。

二、无运行时开销。 构建期生成，运行时零成本。

三、可被浏览器优化。 变量切换只是重绘，不触发重排。

组件里怎么写

<template>
  <button class="btn">点击</button>
</template>

<style scoped>
.btn {
  background-color: var(--accent);
  border-radius: calc(var(--radius) / 2);
  padding: var(--space-item) var(--space-block);
  transition: opacity var(--duration-base) var(--easing-base);
}
</style>

注意这里没有一个魔法数字：

• var(--accent) 而不是 #a94f33
• calc(var(--radius) / 2) 而不是 4px
• var(--duration-base) 而不是 200ms

怎么验证没绕过

验收标准里有一条：改一个 token，全站视觉同步更新。

我的验证方法是改一个不可能看错的值：

// theme.config.ts
accent: { light: '#ff0000', dark: '#00ff00' }

重新构建，全站所有强调色（导航下划线、焦点环、搜索高亮、引用线）都应该变成红绿。

如果有任何一处没变，说明那里是硬编码的。

收益

半年下来，这套做法带来的实际好处：

一、换肤成本 ≈ 0。 想试新的强调色，改两行，刷新。

二、暗色模式不可能漏。 因为颜色全是变量，.dark 块里定义一次就够。

三、设计评审有依据。 讨论"这个圆角是不是太大"时，看的是 theme.config.ts 里的 radius: '0.5rem'，不是某个组件里的 border-radius: 12px。

一句话

设计 token 的价值不在于"有一份变量表"，而在于让绕过它变得比遵守它更麻烦。

这才是系统。