亦舟 https://soarcraft.cn 写代码,做点小工具,偶尔把想明白的事情写下来。 zh-CN Wed, 16 Sep 2026 00:00:00 GMT 测试 https://soarcraft.cn/blog/post-698a11ee https://soarcraft.cn/blog/post-698a11ee Wed, 16 Sep 2026 00:00:00 GMT 2026-09-16T00:00:00.000Z 1 31

]]> 你好,世界 https://soarcraft.cn/blog/hello-world https://soarcraft.cn/blog/hello-world Thu, 10 Sep 2026 00:00:00 GMT 2026-09-15T00:00:00.000Z 这个站点是怎么来的,以及我打算在这里写点什么。 杂记 搭建一个自己的角落这件事,我想了很久。用过各种平台的博客、笔记软件、社交网络,最后发现它们都有同一个问题:那个地方不完全属于你。

为什么要自己搭

平台会改版,会关停,会调整推荐算法。你写的东西散落在别人的数据库里,格式、链接、排版都不由你决定。而一个自己掌控的站点,最坏的情况也不过是换个域名继续活着。

拥有自己的一小块互联网,是件很朴素但很踏实的事。

这里会有什么

大致三类内容:

  • 技术笔记 —— 踩过的坑、想明白的原理、值得复用的方案
  • 项目复盘 —— 做了什么、为什么这么做、哪里做得不够好
  • 一些杂念 —— 读书、工具、以及对日常生活的观察

更新频率不承诺,但会尽量写自己真正想写的东西。

技术选型

这个站用 Next.js + Tailwind CSS 搭建,文章用 Markdown 写在 content/posts/ 目录下,提交后自动构建。没有后台,没有数据库,一篇文章就是一个文件。

简单,可控,能活很久。

]]> 搞懂 React Server Components:一次讲清楚边界在哪 https://soarcraft.cn/blog/react-server-components https://soarcraft.cn/blog/react-server-components Sat, 22 Aug 2026 00:00:00 GMT RSC 不是「在服务端渲染 React」那么简单。真正要理解的是序列化边界,以及它能穿过什么、不能穿过什么。 React Next.js 第一次用 App Router 的时候,我踩了个很典型的坑:在一个 Server Component 里给子组件传了个函数当 prop,然后浏览器控制台给我报了一句话——

Functions cannot be passed directly to Client Components unless you explicitly expose it by marking it with "use server".

当时我只觉得规则很烦。后来想明白了:RSC 的核心不是「服务端渲染」,而是序列化边界。

边界才是重点

服务端组件渲染的结果是一段可以被序列化的数据流(RSC Payload),它要通过网络传给客户端。能穿过这条边界的只有:

  • 普通对象、数组、字符串、数字、布尔、null
  • Date、Map、Set、TypedArray
  • JSX 元素(本身也是可序列化的描述)
  • Promise(会被流式处理)
  • 标记为 "use server" 的 server action 引用

传不过去的是:函数、类实例、Symbol、以及任何带原型的自定义对象。

// ❌ 这样不行
<ClientChart formatter={(v) => v.toFixed(2)} />
 
// ✅ 把格式化的事情留给客户端自己决定
<ClientChart precision={2} />

「use client」不是「这个组件在浏览器跑」

更准确的理解是:它是客户端的入口标记。打包时,构建工具从这个标记开始,把它 import 的所有模块一起打进客户端 bundle。

所以一个常见误区是:以为加了 "use client" 的文件就完全不在服务端执行。实际上客户端组件在 SSR 阶段依然会在服务端跑一遍产出 HTML,只是它不会在服务端「重新渲染」。

什么时候该切到客户端

判断标准其实只有一条:这个组件需不需要响应交互或访问浏览器 API。

需要用到 useState、useEffect、onClick、window、localStorage —— 那就加 "use client"。否则,留在服务端。

一个实用技巧:把 "use client" 尽量往下推。不要给整个页面加,只给真正需要交互的那颗叶子节点加。父级保持服务端,能传给它的 JSX 会作为 children 原样透传,不占用客户端 bundle 体积。

// 页面是服务端组件
export default function Page() {
  return (
    <ThemeToggle>
      {/* 这棵子树依然是服务端渲染的 */}
      <ServerRenderedList />
    </ThemeToggle>
  )
}

小结

  • RSC 的本质是序列化边界,不是渲染位置
  • "use client" 标记的是打包入口,不是执行环境
  • 把客户端边界往下推,bundle 才会小

想清楚这三点,App Router 里 90% 的困惑会自己消失。

]]> 深色模式不该只是换个背景色 https://soarcraft.cn/blog/css-dark-mode https://soarcraft.cn/blog/css-dark-mode Thu, 30 Jul 2026 00:00:00 GMT 把亮色主题反过来写一遍,是最容易出错的做法。聊聊对比度、层次、以及那个恼人的首屏闪白。 CSS 设计 很多深色模式做出来像「把灯关掉」,而好的深色模式应该像「换了个房间」。

不要直接反色

纯黑 #000 配纯白 #fff 的对比度是 21:1,远超阅读需要,长时间看会刺眼,而且在 OLED 屏上会有明显的文字拖影。

我的做法是:背景不用纯黑,文字不用纯白。

:root {
  --bg: #ffffff;
  --fg: #18181b;
  --muted: #71717a;
}
 
.dark {
  --bg: #0b0b0f;
  --fg: #e4e4e7;
  --muted: #a1a1aa; /* 注意:深色下 muted 要更亮 */
}

关键点在 --muted。深色背景上,次要文字需要提高亮度才能保持同样的可读性,直接复用亮色主题的灰度会让正文看不清。

层次靠亮度,不靠阴影

亮色模式里我们用阴影表达「浮起来」。到了深色模式,阴影几乎看不见,应该用表面亮度分层:

  • 页面底色:最暗
  • 卡片:比底色亮一点点
  • 悬浮层/弹窗:再亮一点点

每级大概差 3%~5% 的亮度就够,多了会显得脏。

解决首屏闪白

如果主题存在 localStorage 里,React 水合之前页面已经渲染完了,于是用户会看到一闪而过的亮色。

解法是在 <head> 里塞一段同步执行的内联脚本,在 CSS 生效前就把 class 打到 <html> 上:

try {
  const t = localStorage.getItem('theme') ?? 'system'
  const dark = t === 'dark' || (t === 'system' &&
    matchMedia('(prefers-color-scheme: dark)').matches)
  document.documentElement.classList.toggle('dark', dark)
} catch {}

再给 <html> 加 suppressHydrationWarning,避免 React 因为服务端/客户端 HTML 不一致报警告。

图片和插画

别忘了图片。纯白底的图片在深色模式下会变成一块刺眼的亮斑。一个便宜的处理方式:

.dark img {
  filter: brightness(0.9) contrast(1.05);
}

更好的做法是准备两套资源,用 <picture> 配合 prefers-color-scheme 切换。

最后

深色模式的验收标准很简单:在晚上关了灯,用它读十分钟文章,眼睛不累。达不到就继续调。

]]> 我用的写作工具链:越简单越好 https://soarcraft.cn/blog/writing-tools https://soarcraft.cn/blog/writing-tools Thu, 18 Jun 2026 00:00:00 GMT 折腾过十几款编辑器之后,我回到了纯文本。工具不决定写作质量,但烂工具会显著拖慢你。 工具 杂记 工具折腾了三四年,最后收敛到一套极其朴素的东西。

写作:纯 Markdown

Obsidian 或者其他什么都行,核心是文件就是文件。不锁进某个云服务的私有格式里,不依赖特定客户端才能打开。

我只在写的时候用两三个插件,其余时间保持原生。插件越多,越容易在某次更新后崩掉。

配图:截图 + 极简标注

  • 截图:CleanShot X / Snipaste
  • 标注:能画框画箭头就够了,不需要花哨

发布:git push

写完把 .md 文件丢进目录,提交,推上去,CI 自动构建。整个流程和写代码一样。

这个好处是发布没有心理负担。不用登录后台、不用调排版、不用点一堆按钮。写作和发布之间只隔一个 git commit。

我不用的东西

  • AI 自动配图 —— 风格太统一,反而没了辨识度
  • 复杂的排版工具 —— 排版应该在写的时候就完成,而不是写完再调
  • 阅读量统计 —— 有的话我会忍不住看,然后开始为了数据写

一句实在话

工具链的终极目标是让你忘记工具。当你不再想着「我该用哪个软件写」的时候,这套工具链才算配好了。

]]>