赛博空间

一、页面转场：为什么它值钱#

传统多页站点的跳转是白屏 → 新页面。而 swup 做的事情是：拦截站内链接，只替换 <main> 容器，然后做一次入场动画。

1
swup({
2
  containers: ["main", "#toc"],
3
  smoothScrolling: true,
4
  cache: true,
5
  preload: true,
6
  animationClass: "transition-swup-",
7
});

几个关键点：

• containers 必须包含所有会变化的区域。只写 main 而漏掉目录，侧边栏的 TOC 就会停留在上一篇文章的内容上。
• cache: true 会缓存已访问页面，返回时几乎瞬开。
• preload: true 在鼠标悬停时就开始预取，点击时内容已经就位。

NOTE

动画类的命名不要用默认的 transition- 前缀。它和 Tailwind 的 transition-all 撞车，会导致转场延迟——页面内容已经换完了，动画还在原地发呆。

二、搜索：纯静态方案#

Pagefind 在构建完成后扫描 dist，把索引切成小块按需加载。首次搜索大约只下载几十 KB，不需要任何后端。

1
astro build && pagefind --site dist

TIP

如果你发现搜索结果为空，八成是构建顺序错了：必须先 build 出 dist，再跑 pagefind。反过来索引里什么都没有。

三、明暗主题与主题色#

主题色不是写死的十六进制，而是一个 hue 值：

1
:root {
2
  --hue: 265;
3
  --primary: oklch(0.7 0.18 var(--hue));
4
}

这样只要改一个数字，全站的强调色、链接、按钮、代码高亮边线会一起换掉，而且颜色始终处在同一个色系里，不会出现某个元素不搭的情况。

设计系统里最划算的投资，就是把颜色收敛成一个可计算的变量。

四、那些文档里没写的坑#

1. trailingSlash 必须和托管平台一致。站点用 always、平台按 never 处理，就会出现一堆 404 或者重复 URL。
2. site 配置要填真实域名。它决定了 RSS、sitemap 和 OG 图里的绝对地址，填错的话分享到社交平台会抓不到缩略图。
3. 图片交给构建期处理。把图放在 src/assets 而不是 public，Astro 会自动压缩、转格式、加宽高，避免布局抖动。

最后#

整套流程跑通之后，写一篇文章的成本就只剩下「写」本身了。这才是搭博客真正的目的——让工具消失在写作背后。