home

blog

trace

about

design

portfolio

Copyright © 2026|All rights reserved by Yvan

个人博客搭建历程

2025年09月20日15 分钟
codeblogmdxnextjs

我打开一个空文件夹,准备给自己搭一个博客。几分钟后,我已经在一堆浏览器标签页之间来回切换:这个框架说自己是下一代,那个工具说自己零配置,还有一篇文章标题写着「你还在用 X?」。我什么字都还没写,就已经开始焦虑了。

坦白说,这种焦虑我并不陌生。前端的技术丛林每个月都有新树长出来,而我总以为只要选对了工具,剩下的事就会自己顺起来。

这篇文章会讲我最后怎么走出来的:选了什么,丢了什么,哪些地方我白白折腾了一个周末。重点是几处性能和体验上的坑,以及我从中得到的判断。适合谁读:正打算给自己搭站、又被选型搞得头大的人。

个人博客不需要那么多东西

一个人写的博客,读者是你自己加上几个偶尔路过的人。它不需要微服务,不需要后台管理界面,也不需要「内容中台」。它需要的是:写起来顺手,读起来舒服,三年后还能打开。

我给自己定了一条规矩:文章必须是文件,而不是数据库里的一行记录。文件可以用编辑器改,可以进 git,可以在服务器挂掉的时候躺在硬盘里。这条规矩一下子砍掉了一半候选方案。

技术选型最贵的成本,不是学习,而是三年后你想换掉它的时候。

选 Next.js,因为我不想再做第二次决定

框架我没纠结太久。Next.js 16 的 App Router,加上 React 19 和 TypeScript,是我日常最熟的组合。个人项目里,「熟」比「最优」值钱得多,因为你每天只有很少的时间,不应该花在查文档上。

样式用 Tailwind v4。我最满意的是 @theme:颜色、字号、间距这些 token 直接写在 globals.css 里,不再需要单独的配置文件,改一个变量,整个站点跟着变。

动画用 motion,主题切换用 next-themes,再加一个基于 CSS View Transition 的切换动画。这些的代价是什么? 它们都是锦上添花,但后面你会看到,最贵的恰恰就是这些锦上添花。

让文章变成代码的那条流水线

内容层我用 Velite。流程很简单:每个 .mdx 文件在构建时被编译成一个可序列化的函数,同时抽出 frontmatter 和目录树;渲染时,服务端把函数还原,注入自定义组件,输出 HTML。

插件只装了几个:remark-gfm 负责表格和任务列表,rehype-slug 给标题加 id,rehype-autolink-headings 加锚点。代码高亮用 prism-react-renderer,需要在线编辑的地方交给 Sandpack。

这套东西写起来接近在本地编辑 Markdown:保存之后,浏览器一秒内刷新。我很在意这一点,因为写作的冲动是脆弱的,任何等待都会把它掐灭。

为什么是 Velite,而不是 Contentlayer?

一个小按钮,三次踩坑

深色模式的切换按钮是我花时间最多的「小东西」。View Transition API 能让整页平滑过渡,用起来只有几行,但细节全在边界上:不支持的浏览器要直接降级,过渡被打断时 Promise 会抛 InvalidStateError,状态更新还必须同步,否则快照拍到的是旧页面。

dark-mode.tsx

1
if (typeof document.startViewTransition !== "function") {
2
apply(); // 不支持就直接切换,不做动画
3
return;
4
}
5
const transition = document.startViewTransition(apply);
6
transition.ready.catch(() => {}); // 被打断时安静地失败
7
await transition.finished.catch(() => {});

注意高亮的两处:开头的降级分支,和末尾两个被吞掉的 Promise。我最后的做法很朴素:动画完全交给 CSS,JS 只负责切换状态,因为主题已经切过去了,用户并不关心动画有没有跑完。对装饰性的东西,失败了就安静地失败。

所谓「体验」,常常不是做加法,而是把异常路径一条条堵上。

一个页面,同时是设计系统

2026 年 6 月 20 日,我做了一次很大的集中改动:目录的滚动联动(带一个会滑动发光的小圆点)、脚注、图片灯箱,还有 Details、Video、Gallery、Sandpack 这一批组件。同一天我还加了 /design 页面,它表面上是展示页,实际上是整个站点的设计系统:每个 token、每个组件,都按真实样子摆在那里。

为什么要这样做?因为一个人维护的项目最大的敌人是遗忘。三个月后我已经不记得某个按钮为什么是那个圆角,但只要打开 /design,答案就在页面上,不在我的脑子里。hello.mdx 也被我改写成一篇「全功能展示」的文章,既是示范,也是回归测试。

给自己写的文档,只有一个标准:三个月后的你读得懂。最好让它是一个能跑起来的页面,而不是一段需要手动维护的说明文字。

后端和字体,才是真正花时间的

静态博客也有几个绕不开的动态需求:点赞和浏览量、联系表单,还有一个需要密码才能进的作品集页面。点赞最早放在 Upstash Redis 上,2025 年 9 月 22 日我把它迁到自己的服务器,用 Postgres 存数据,访客身份由 FingerprintJS 生成。联系表单走 nodemailer,/portfolio 的口令验证是一个用 SESSION_SECRET 签名的 cookie,没有第三方登录,也不需要。

2026 年 7 月,我给这些接口补了一轮安全加固:CSRF 校验、限流、来源检查,以及 CI 里把第三方 Action 固定到 commit SHA。没有一件是好玩的,但只要站点上有一个能写数据库的接口,就该做。

字体是另一个隐形的大头。中文字体动辄几 MB,我把它自托管并做了子集化,其中一个 4.27MB 的字体变成了 55KB。这一步带来的收益,比我写过的任何一行优化代码都大。

慢的不是体积,是编排

到了 2026 年 11 月,我终于坐下来认真做了一次性能检查。出发前我以为问题在包体积,结果大部分问题出在动画的编排上。

最典型的是手机上的导航菜单。点开要等大约一秒,我一直觉得是「手机慢」。其实是我自己写的 framer variants 里带了 beforeChildren 和 afterChildren,让父元素先动完、子元素再依次动,十个链接又各自加了 0.08 秒的错开。时间被我一层层串行叠了上去。

header-section.tsx

1
// 之前
2
transition: { when: "beforeChildren", staggerChildren: 0.08 }
3
4
// 之后:父子并行,错开缩到 0.03s
5
transition: { duration: 0.2, ease: "easeOut", staggerChildren: 0.03 }

注意高亮的两行:串行的 when 没了,错开从 0.08 缩到 0.03。改完之后,菜单完全展开从 1019ms 降到 301ms,关闭从 1228ms 降到 172ms,视觉上几乎没有变化。这是用 puppeteer 做移动端模拟测出来的数字,我不打算替它们背书更多。

同一轮里还有几处类似的发现:

  • 页头在每一帧滚动里都在重新渲染,改成用 ref 记录上次位置,只在状态真正变化时才 setState。
  • 动画背景的模糊从整体挪到了每个色块上,GPU 的压力小了很多。
  • 首屏的 LCP 图片不再等 hydration 才出现,我观察到的 LCP 从 1208ms 降到 851ms。
  • cn() 原本和 date-fns 住在同一个文件里,拆开之后首页 JS 从 280KB 降到 250KB(gzip)。

这些数字来自模拟环境,不同设备上会有出入。我的经验是:别信自己的直觉说「手机慢」,先量一遍。

最后一条是我最喜欢的小改动。禁止双指缩放,我原来是在 document 上挂一个非 passive 的 touchstart 监听,它会拖慢滚动。后来发现一行 CSS 就够了:

globals.css

1
html { touch-action: pan-x pan-y; }

回头看,这些改动几乎都不是在写新代码,而是在删代码:删掉一个监听器,删掉一层串行的时序,删掉一个多余的重渲染。浏览器本来就有现成的机制,而我却自己造了一个更慢的。

回顾一下

2025 年 9 月 22 日的第一次提交走到现在,我最大的收获不是某个技术,而是几条朴素的判断。2026 年 6 月 21 日我花了一天做手机端适配,才发现自己之前几乎都在大屏上验收,而不少读者是在地铁上用拇指翻页。

  • 先写文件,再谈系统:文章是 .mdx,所有东西都围绕它长出来。
  • 动画先问编排,再问体积,用户感觉到的卡顿往往来自没认真想过的时序。
  • 生态永远在推你多装一点;three.js 只在 /movie 用且手机上不加载,/about 的地球是 cobe 画的,粒子用 tsparticles,统计用 Umami,每个依赖我都问过「它不存在的话,读者会少什么」。
  • 对装饰性的东西,失败了就安静地失败。

技术丛林永远不会变稀疏,能做的只是认准方向,偶尔砍掉几根挡路的藤。如果你也站在那个空文件夹前,先写下第一篇文章,再回头决定它该住在哪里。

Made By Yvan
One Article, the Whole Writing SystemA Field Guide to Small Sparks