Yunfi Blog

更快地初始化 Shiki 代码高亮

Sat, 11 Oct 2025 08:17:43 GMT

TIP: 在 RSS 阅读器中，一些组件可能无法正常显示。在浏览器中打开以获得更好的阅读体验。

Shiki 作为热门的代码高亮库，通过 rehype 插件使用时由于默认情况下需要加载所有主题和语言定义，导致初始化的性能不太能被接受。本文简单分享一些在本网站中使用的按需加载 Shiki 资源的思路。

问题

我是以 rehype 插件的形式使用 Shiki 的，这种方法默认会在内部创建一个包含了所有主题和语言定义的 highlighter 实例。而由于主题和语言定义都是通过动态 import() 加载的，导致第一次创建时的性能非常差：在本地机器（M2 Pro）上，需要大约 2500ms，而在 Vercel 的构建机器上需要 8000ms 以上。

(feed.xml 是第一个需要渲染代码高亮的页面，通过去除代码高亮功能来进行对比，可以发现它主要的开销就是 Shiki 的初始化)

而如果是实时服务端渲染的场景，如果是 Serverless 冷启动的情况，那每个请求都会需要初始化一次 Shiki，加载速度完全没法接受。本站之前使用 Next.js + RSC 渲染博客文章时非常依赖 Route Cache，否则每次访问都需要等待5秒以上。

按需加载

对于这种初始化慢的问题，Shiki 文档中给出的解决方法是使用 Fine-grained Bundle，只加载需要的主题和语言定义。

最容易优化的是主题的加载：一个站点使用的主题肯定是提前选择好的，因此可以直接指定好需要的主题。

const highlighter = await createHighlighterCore({
  themes: [import('@shikijs/themes/vitesse-light')], // 只加载一个主题
  langs: [], // 稍后再说语言的加载
  engine: createOnigurumaEngine(() => import('shiki/wasm'))
})

然而语言定义的加载就相对复杂：Shiki 支持的语言中，我有一大部分这辈子可能都不会用到；但另一方面，我既不知道以前曾经在博客文章中在代码块中使用过哪些语言，更不知道未来可能会使用哪些语言，因此无法提前在代码中指定需要加载哪些语言定义。

因此，语言的加载只能是实时、按需的，我的思路是，在 shiki 的 rehype 插件之前再添加一个 rehype 插件，它会扫描出代码块中使用过的语言，将它们添加进 highlighter 的语言定义中，之后的 shiki rehype 插件就可以直接使用这个 highlighter 了。

完整代码：

import rehypeShikiFromHighlighter from "@shikijs/rehype/core";
import type { Element } from "hast";
import { createHighlighterCore } from "shiki/core";
import { createOnigurumaEngine } from "shiki/engine/oniguruma";
import { bundledLanguages, type BundledLanguage } from "shiki/langs";
import { bundledThemes } from "shiki/themes";
import type { Pluggable, Plugin, Preset } from "unified";
import { visit, CONTINUE, SKIP } from "unist-util-visit";

const highlighter = await createHighlighterCore({
  themes: [bundledThemes["catppuccin-macchiato"]],
  // initially empty, the `rehypeCodeLangDetecter` will load the languages
  langs: [],
  engine: createOnigurumaEngine(() => import("shiki/wasm")),
});

const loadedLangs = new Set<string>();

const shikiPluggable: Pluggable = [
  rehypeShikiFromHighlighter,
  highlighter,
  { theme: "catppuccin-macchiato" },
];

export const rehypeShikiPreset: Preset = {
  plugins: [rehypeCodeLangDetecter, shikiPluggable],
};

function rehypeCodeLangDetecter(): ReturnType<Plugin> {
  return async (tree, file) => {
    const langs: string[] = [];
    visit(tree, "element", (node: Element) => {
      if (node.tagName !== "code") return CONTINUE;
      if (!node.properties.className) return CONTINUE;
      const className = node.properties.className;
      if (!Array.isArray(className)) return CONTINUE;
      const lang = className.find(
        (cls): cls is string =>
          typeof cls === "string" && cls.startsWith("language-"),
      );
      if (!lang) return CONTINUE;
      langs.push(lang.slice("language-".length));
      return SKIP;
    });
    file.data.langs = langs;
    for (const lang of langs) {
      if (loadedLangs.has(lang)) continue;
      if (!(lang in bundledLanguages)) continue;
      const langRegistration = bundledLanguages[lang as BundledLanguage];
      await highlighter.loadLanguage(langRegistration);
      loadedLangs.add(lang);
    }
  };
}

highlighter 是一个模块级别单例，在当前 JS Context 中，所有的代码高亮都由这个实例完成。
loadedLangs Set 用于记录已经加载过的语言，避免重复加载带来的开销。
rehypeCodeLangDetecter 插件会扫描出代码块中使用过的语言，并将它们加载到 highlighter 中。
1. 由于 remark-rehype 插件会将非 inline 的 Code 节点转换成 <pre><code class="language-xxx">...</code></pre> 的形式，而 inline 或者没有指定语言的代码块不会含有 language-xxx 的 class，因此只需要扫描 className 即可。
2. 同时会将语言信息存储在 file.data.langs 中，方便后续其他插件使用。
rehypeShikiFromHighlighter 插件使用这个 highlighter 来进行代码高亮。
rehypeShikiPreset 是一个 rehype preset，可以直接在 unified 的处理链中使用。

使用示例：

const vfile = await unified()
      .use(remarkParse)
      .use(remarkRehype)
      .use(shikiPreset) // 直接使用上面定义的 preset
      .use(rehypeStringify)
      .process("your markdown content");
const html = String(vfile);

效果

一个简单的 benchmark 可以发现加载3个语言比加载所有语言快 3000 倍。（作为一个 micro benchmark，这个结果仅供图一乐）

而在实际渲染时，第一个使用 highlighter 的路由渲染时间从 10s+ 降低到了不到 2s，性能差距非常明显；而后续的请求虽然不需要重新初始化 highlighter，但可能是因为使用的语言少，普遍也有约 20% 的性能提升（从这也可以看出来，代码高亮是主要的性能瓶颈）。

参考

在 Markdown 中使用 React 组件

Mon, 29 Sep 2025 16:15:48 GMT

TIP: 在 RSS 阅读器中，一些组件可能无法正常显示。在浏览器中打开以获得更好的阅读体验。

我想在我的 Markdown 博客文章中嵌入一些简单的 React 组件——想做到很容易，想做好却并不简单。

需求

最主要的诉求是可以在 markdown 渲染出的网页（比如现在这篇博客文章）中嵌入一些 React 组件，比如代码块的复制按钮、GitHub 仓库信息卡片等。

还有一些额外的需求：

尽可能少地增加 JavaScript 包大小（或者其他需要网络传输的数据大小）
SSR/水合友好。
最好可以做到框架无关。
不要使用 MDX。这个需求比较个人，具体原因可以看文末的为什么不用 MDX。

Markdown 如何包含 React 组件？

一个简单的方法是使用 HTML 的 custom element 作为中间表示，比如将 markdown 转换成 <github-card data-repo="yy4382/yfi.moe" />，然后在最后渲染的时候通过一些办法用 React 组件替换这些 custom element（本文的重点就是通过什么办法做替换）。

这种方法的好处是不会限制使用的 markdown 处理器，更换起来比较简单。

我使用的是 remark / rehype 这个生态系统，这种情况下实际上不需要序列化成 HTML，在转换成 HTML 的 AST hast 后就可以使用 hast-util-to-jsx-runtime 库将这些自定义元素转换为 React 组件了。

同时，其实我们并不需要在 markdown 中手动写这些 custom element，可以使用 remark / rehype 插件。比如，如果想要给每个代码块添加一个 copy button，我就编写了一个插件自动添加；Markdown 还有一个不在 CommonMark 标准但社区广泛采用的 directives 提案，可以使用它实现更有 markdown 风格的 GitHub 卡片 ::github-repo{repo="yy4382/yfi.moe"}。

欠优化的方法

先介绍两个我尝试过，但是因为缺点太明显，以至于没有实际上线过的方案：

直接用 react-markdown 库：我为什么要把整个 remark/rehype 工具链发到客户端？我只是想展示一篇博客文章而已。
使用 react-dom 的 createPortal 来将组件插入到对应位置：在服务端 createPortal 不会跑（因为没有真实 DOM），不能 SSR。

方法一：RSC 就是为此而生的

[!NOTE] 优点：简单易实现

缺点：必须得有 RSC 才能用；RSC payload 可能过大

直接用 react-markdown 会导致超大的包大小，那我把它放进 RSC 里不就行了吗？

如果你有幸（或者不幸）使用了 Next.js¹，那么这种方法简单易操作，不需要用到（后文会提到的）各种奇技淫巧。

然而这种方法也有一些小问题：

显然只能在支持 RSC 的框架中使用
RSC Payload 会很大：每个 <p> 或者 <div> 都会以 RSC 的格式存在于 payload 中；而 RSC 格式虽然相对于 React 组件代码来说很紧凑，但是和 HTML 相比还是大不少。在使用类似 shiki 这样的高亮库后，高亮部分更是会让 RSC payload 急速膨胀：代码块一多，RSC payload 甚至可能比直接把 react-markdown 发到客户端还要大。一种缓解办法是把代码块部分直接用 dangerouslySetInnerHTML 插入，就不用为其中每个 token 都生成 RSC 表示了（示例代码）。本博客曾经有过一段时间使用的是 Next.js，当时就是使用的这种思路，只是稍有更改：没有直接使用 react-markdown，而是将 markdown 转换到 hast 和 hast 转换成 React 组件分了开来。当时的代码在博客开源仓库的 nextjs-attemp tag 下：yy4382/yfi.moe at nextjs-attempt。

方法二：手动 SSR + hydrateRoot

[!IMPORTANT] 这是本博客目前使用的方式，也是我目前最推荐的。

[!NOTE] 优点：几乎不会额外增加包体积；可选的 SSR 与水合；适用于大部分框架

缺点：在 React 框架中会有一些小问题

该方法是针对 React 18+ 设计的，之前的版本我也没研究过。（hydrateRoot API 都是在 18 的时候才加的）

这个方法的思路是：

服务端中，在上文提到的包含 custom element 的中间表示 AST 基础上，新增的一个插件，调用 react-dom 的 renderToString 将所有 custom element 转换成真实 React 组件渲染出的结果，这步也就是「手动 SSR」；
序列化为 HTML 后，使用框架提供的方法直接插入 DOM（如 Astro 的 set:html prop）。这步也是在服务端完成的；
在客户端，对每个需要变成 React 组件的元素使用对应的 React 组件调用 hydrateRoot，这样组件就变得有交互性啦。性能方面，经我测试，对于不太复杂的组件（比如复制按键、GitHub Card 等），数百个 Root 并不会对性能有什么影响。考虑到 Astro 就是用类似的方法实现的 islands 架构且运行良好，这种方法在大多数情况下应该不会有性能问题。

思路实现

一些目前我在 Astro 中使用的示例代码（链接中都固定使用了编写本文时的最新 commit，这样可以保证行号不会因为之后更改而变动；如果 commit 消失了可以去 main 分支里找一下）：

关键文件：yfi.moe/app/blog-astro/src/components/markdown/markdown-article.astro at 304eb8 · yy4382/yfi.moe

文件 25-48 行向我的 markdown 渲染管线中添加了新插件，用于将两个 custom element 转换成对应的 React 组件渲染出的 HTML fragment；
54 行直接将转换出的 HTML 插入
66-84 行会在客户端运行，找到所有需要转换成组件的元素，对每个元素调用 hydrateRoot；同时别忘了在页面卸载时 unmount 它们。

缺陷

这种方法在 React 框架（比如 Next.js）中会有一些问题，我也还没有完全弄清原因；不过对于「在 React 创建维护的 DOM 中创建新的 React Root」这种奇怪用法，出现一些问题也在情理之中。

当时我在 Next.js 中的设置是这样的：

一个 server component，它负责生成 markdown 转换出的 HTML，将它 setHtml 进 jsx 里；
一个返回 null 的 client component，它只有一个 useEffect，effect 中对所有元素进行水合，并且返回一个 unmount 它们的清理函数。它是上文 server component 的子组件。遇到了如下问题：
由于 Next.js 编译器的人为限制，在服务器组建中不让导入 react-dom 的 API，而我需要它们来手动 SSR。最后通过动态导入骗过了编译器；
unmount 时会报错。目前怀疑是因为是在 Effect 中调用的，React 18 后的 concurrent rendering 可能不允许在 effect 中 unmount 掉 root，即使是完全无关的其他 root。

方法三：将 HAST 传到客户端

[!NOTE] 优点：适用于所有地方，新增的包大小并不大；

缺点：还是需要新增一些需要网络传输的数据。

如果我使用的是 React 框架，并且它还不支持 RSC 怎么办？我们还有第三种方法。

react-markdown 很大，但我们在客户端并不需要它们全部：我们可以在服务端提前将 markdown 转换为 HTML 的 AST 表示 hast，然后将它发送到客户端；在客户端用不太大的 hast-util-to-jsx-runtime 库再将 hast 转换成 React JSX。

这样，我们只付出了需要多传输 hast-util-to-jsx-runtime 库和文章 hast 的代价，就获得了一个几乎可以在任何地方运行的方案。

为什么要多传输 hast 而非直接从完整的 HTML 里提取出需要的部分转换成 hast 再传给库？因为 HTML 转 hast 的库太大了……而 hast 由于与预渲染的 HTML 相似度较高，gzip 传输时增加的大小并不大。

[!TIP] HAST 默认在节点中附带位置 map 信息，记得把它们去掉，不然 hast 会很大。

这个方法本网站也曾经使用过，效果也还不错。

效果展示

复制按钮

每个代码块都会自动添加一个复制按钮。

function Hello() {
    return <div>Hello, world!</div>; 
}

GitHub 仓库信息卡片

::github-repo{user="yy4382" repo="yfi.moe"}

::github-repo{user="yy4382" repo="yfi.moe"}

注

为什么不用 MDX？{#why-not-mdx}

主要是需求原因。我的需求目前只有复制按钮和 GitHub Card，未来即使增加也只会是一些通用的组件；MDX 可以导入任意组件的优势并不成立；我也不想因为这些小需求将我已有的 md 都转换成 mdx。

同时，MDX 应该被视作「代码源文件」而非普通的纯文本文件，这很不「可移植，portable」。MDX 实际上会被编译成 JavaScript 脚本，它有「依赖」，是文件路径敏感的（而我的 markdown 文件甚至是在另一个 GitHub repo 中，是需要构建时从网络上拉下来的）；而普通 markdown 一般会被转换成 HTML fragment，这也是可以当作一个字符串到处传来传去的。有了这样的可移植性，如果未来想完全重写网站，只需要保留好现有的、组件无关的、路径无关的 markdown 转换管线，就可以轻松迁移。

截止本文成稿，Next.js 仍然是唯一在生产级别支持 RSC 的 Meta Framework。 ↩

Rust TUI 事件处理：从 TEA 到组件化

Mon, 02 Jun 2025 00:00:00 GMT

TIP: 在 RSS 阅读器中，一些组件可能无法正常显示。在浏览器中打开以获得更好的阅读体验。

最近用 Rust 开发了一个 TUI 程序，对于 TUI 中的事件处理有了一些心得，写篇文章分享一下。

主要内容包括：

TUI 程序的基本运行模型
TEA 架构：一种优雅的事件处理模式
组件化带来的事件处理新挑战
如何构建多页面 TUI 程序

[!NOTE] 本文为一次课程分享的内容整理，尝试了一下用 AI 将我的 slides 和讲稿转换成了这篇博文，所以遣词造句的 AI 味儿可能比较浓，但内容本身是我自己编写的。

TUI 程序是如何运作的？

要理解 TUI 开发，首先得明白它的基本运行模型。我们可以将其简化为以下几个核心概念：

状态（State）：应用程序自身拥有的数据和当前状况。
UI 显示（UI Display）：可以看作是当前状态的一个函数。它将状态渲染到终端屏幕上，供用户查看。
事件（Event）：用户的操作（如键盘输入）、系统信号或其他外部输入。事件会触发状态的更新。
主循环（Main Loop）：程序的核心部分，会不断地尝试从终端读取新的事件，并驱动后续的逻辑。

这个模型可以用一个简单的流程图来表示：用户操作产生事件 -> 事件更新状态 -> 新状态渲染为 UI。

TUI 开发的核心任务

从上述模型中，我们可以清晰地将 TUI 的开发工作划分为两个主要部分：

根据“状态”渲染“UI 显示”（渲染 UI）：这部分关注如何将程序内部的状态数据，通过一定的布局和样式，绘制到终端界面上。
处理“事件”并更新“状态”（事件处理）：这部分关注如何接收用户的输入或其他事件，并根据这些事件来修改程序的状态，从而驱动界面的变化。

对于UI渲染，市面上有不少优秀的库可以帮助我们，例如在 Rust 生态中，ratatui 就是一个广受欢迎的选择。通过为自定义的状态结构实现 ratatui::Widget trait，我们就能利用 ratatui 提供的 Backend::draw 函数将 Widget 转换为终端缓冲，最终呈现在用户面前。

然而，事件处理往往是 TUI 开发中复杂度的主要来源。与UI渲染不同，这部分通常没有现成的库能够完美覆盖所有需求，更多时候需要我们自己设计和实现。本次分享将更偏向工程实践，旨在以尽量优雅的方式解决事件处理中遇到的问题。

TEA 架构：一种优雅的事件处理模式

在处理相对简单的应用逻辑时，我们可以直接响应事件并更新状态。但随着应用功能的增加，状态和事件的种类会急剧膨胀，直接处理将变得混乱不堪。这时，引入一种结构化的架构就显得尤为重要。

The Elm Architecture（TEA）是一种源自 Elm 语言的函数式 UI 架构，它将 UI 视为一个状态机，非常适合管理复杂的状态更新。一个标准的 TEA 应用主要由三部分组成：

Model：即应用程序的当前状态。
Update：一个函数或方法，它接收一个 Action（有时也称为 Message），并根据这个 Action 来更新 Model。
View：一个函数或方法，它接收当前的 Model，并将其渲染到屏幕上。

在 Rust 中，我们可以将一个 TEA 组件实现为一个 struct，并为其定义 render (对应 View) 和 update (对应 Update) 方法。

TEA 架构的核心优势在于它借鉴了状态机的思想。这种思想使得它在保持概念简单易用的同时，能够清晰、有序地处理复杂的状态转换逻辑。

示例：一个简单的 TODO 应用

让我们通过一个简单的 TODO 应用来看看 TEA 如何运作。假设我们的 TODO 应用有一个输入框用于添加新的 TODO事项，一个提交按钮，以及一个显示 TODO 列表的区域。我们暂时只考虑纯键盘操作。

首先，定义应用的状态（Model）和可能的操作（Action）：

Model (状态):

enum Focus { // 表示当前哪个组件拥有焦点
    Input,
    Submit,
}

struct TodoModel {
    todos: Vec<String>,      // TODO 事项列表
    input_buffer: String,  // 输入框中的当前文本
    focus: Focus,            // 当前焦点位置
    edit_mode: bool,         // 输入框是否处于编辑模式
}

Action (操作):

最初我们可能想到这些操作：

enum Action {
    Add(String),       // 添加一个新的 TODO
    MoveFocus,         // 移动焦点 (例如在输入框和提交按钮间切换)
    ToggleEditMode,    // 切换输入框的编辑模式
}

随着思考深入，我们会发现需要更细致的 Action 来处理输入：

enum Action {
    Add(String),
    MoveFocus,
    ToggleEditMode,
    InputKeyEvent(KeyCode), // 代表一个键盘输入事件，传递给输入框处理
}

Update (更新逻辑):

update 函数会根据传入的 Action 来修改 TodoModel：

Add(String): 向 TodoModel::todos 列表中添加一个新的字符串。
MoveFocus: 切换 TodoModel::focus 的值（例如从 Input 到 Submit，反之亦然）。
ToggleEditMode: 翻转 TodoModel::edit_mode 的布尔值。
InputKeyEvent(KeyCode): 当输入框处于编辑模式时，此 Action 会根据具体的 KeyCode (如字符、退格、回车) 来相应地修改 TodoModel::input_buffer。

Event 到 Action 的转换:

用户的原始按键事件（Event）需要被映射到我们定义的 Action：

当 edit_mode 为 false（非编辑模式）时，左右方向键事件可能映射到 MoveFocus Action。
当焦点在提交按钮（focus == Focus::Submit）上时，按下回车键（Enter）映射到 Add(input_buffer.clone()) Action。
当焦点在输入框（focus == Focus::Input）且不是编辑模式（!edit_mode）时，按下回车键触发 ToggleEditMode Action，进入编辑模式。
当 edit_mode 为 true（编辑模式）时：
- 大部分按键（如字母、数字）触发 InputKeyEvent(key) Action。
- 按下 ESC 键触发 ToggleEditMode Action，退出编辑模式。
...等等其他可能的映射。

当应用逐渐变大：组件化

可以看到，即使是上述这个非常简单的 TODO 应用，其事件处理逻辑（特别是 Event 到 Action 的转换部分）也可能迅速膨胀到数十甚至上百行代码。如果继续使用单一的、巨大的 TEA 结构来构建更复杂的真实世界应用，我们会面临几个严峻的问题：

Action 枚举爆炸：随着功能增多，Action 的种类会越来越多，导致 update 函数变得异常冗长，各个逻辑分支高度耦合，难以维护。
Model 状态臃肿：单一的 Model 需要维护应用中所有细枝末节的状态，使得状态管理变得异常困难和混乱。
代码复用困难：如果应用中有一些通用的控件（如自定义按钮、列表视图等）被多次使用，我们将不得不重复编写相似的状态定义和事件处理逻辑。

这些问题的解决方案，相信大家都很熟悉，那就是：组件化。

我们可以将 UI 拆分成一系列更小、可管理的组件。每个组件拥有自己独立的状态（Model）、事件处理逻辑（Update）和 UI 渲染方法（View）。组件可以被复用，从而有效地解决上述三个问题。

然而，在凡事几乎都要亲力亲为的 TUI 系统中引入组件，也为事件处理带来了新的挑战。

组件化带来的事件处理新挑战

引入组件后，事件不再是简单地由顶层应用统一处理，而是需要在组件树中进行分发和响应。这主要涉及两个方面：事件的向下传播和事件的向上冒泡。

1. 事件的向下传播：哪个组件来响应？

回想一下，在常见的图形 UI 应用中（例如 Web 开发），事件通常是如何被处理的？以一个 HTML 按钮为例：

button.addEventListener('click', () => { /* 执行某些操作 */ });

整个过程大致是：

浏览器接收到一个“用户在屏幕 (x, y) 位置点击了一下”的原始事件。
浏览器通过命中检测，发现位于 (x, y) 位置的是一个 <button> 元素。
浏览器随后调用这个 <button> 元素上注册的 click 事件监听器。

然而，在我们的 TUI 应用中，并没有一个类似“浏览器”的角色来帮我们判断哪个组件被“点击”了（因为 TUI 通常是基于键盘交互的，没有鼠标点击位置的概念，只有按键事件）。我们只知道用户按下了某个按键，那么，这个按键事件究竟应该由组件树中的哪一个组件来处理呢？这成为了我们需要解决的首要问题。

解决方案其实并不复杂，我们在之前的 TODO 例子中已经不自觉地使用过它的雏形：焦点（Focus）。

每个父组件，如果它包含子组件，可以维护一个类似 Option<Focus> 的状态。这个状态指明了当前哪个子组件拥有焦点。如果该状态为 None (或某个特定值代表自身)，则表示焦点在父组件自身。

当一个事件（如按键事件）到达父组件时：

父组件首先检查其 focus 状态。
如果 focus 指向某个子组件，则将该事件向下传递给那个子组件。
如果 focus 表示焦点在自身，则由父组件自己处理该事件。

这个过程可以递归地进行下去，直到事件被某个最深层拥有焦点的组件处理，或者在某个层级被消费掉。这样，我们就建立起了一套事件向下传播的机制，确保了事件能够被正确的组件接收。

2. 事件的向上冒泡：子组件如何影响父组件或全局？

在某些 UI 系统中，事件在被处理后，默认会向上“冒泡”到其父组件，父组件也可以选择处理该事件。例如，在 Web 的 DOM 结构中：

<div>
  <button>Click me</button>
</div>

当用户点击 <button> 元素时，浏览器会首先调用 <button> 元素的 click 事件监听器。在默认情况下（如果事件没有被显式阻止冒泡），<div> 元素的 click 事件监听器（如果存在的话）也会被触发。

这种冒泡机制在 TUI 中同样非常有用。考虑以下场景：

我们有一个列表组件，用户可以使用上下方向键来滚动列表或选择列表项。
同时，我们希望整个应用的根组件能监听 'q' 键，当按下 'q' 键时，应用退出。

如果当前焦点在列表组件上，用户正在用上下键浏览。此时若用户按下 'q' 键，我们期望的是应用能够退出，而不是列表组件尝试去处理 'q' 键（除非列表组件本身对 'q' 键有特定含义并希望优先处理）。这就需要事件能够从列表组件向上冒泡到根组件。

控制事件冒泡：

然而，并非所有事件都应该无条件地向上冒泡。组件应该有能力动态地决定一个事件在被自己处理后，是否还应该继续向上冒泡。例如：

根组件监听 'q' 键以退出应用。
根组件中包含一个文本输入组件。当该输入组件内部的 inputting 属性（表示正在输入文本）为 true 时，如果用户按下 'q' 键，我们希望的是字符 'q' 被输入到文本框中，而不是导致应用退出。

在这种情况下，当输入组件处理了 'q' 键并将其作为输入字符后，它应该阻止该事件继续向上冒泡。

有两种初步看来可行的实现方式，但它们各有弊端：

子组件持有父组件引用：子组件包含一个指向其父组件的引用。当需要冒泡时，子组件直接调用父组件的事件处理方法。
- 弊端：在 Rust 这样的语言中，这种方式非常棘手。事件处理通常需要对组件状态进行可变借用（&mut self）。如果父组件持有子组件，子组件又持有父组件的可变引用，很容易形成循环引用或违反借用规则，导致生命周期管理变得异常复杂。
父组件读取子组件状态：父组件在决定是否处理一个可能由子组件冒泡上来的事件前，先去读取子组件的内部状态（例如，上例中的 inputting 属性），以此判断子组件是否已经“消费”了该事件或希望阻止冒泡。
- 弊端：这种方式会导致父组件和子组件之间产生深度耦合。子组件内部状态的任何变更，如果影响到冒泡逻辑，都可能需要同步修改父组件的代码，降低了组件的独立性和可维护性。

一种在 Rust 中更优的思路：

我们可以换一种思路，让组件的事件处理函数的返回值来决定事件是否继续冒泡。例如，事件处理函数可以返回一个枚举 EventStatus，它包含 Bubble（继续冒泡）和 Stop（停止冒泡）两个变体。

或者，我们可以直接从 Web API 中汲取灵感，为事件对象本身添加一个类似 stop_propagation() 的方法。子组件在处理事件时，如果调用了这个方法，那么父组件在接收到（或准备接收）这个事件时，可以检查其状态，如果已被标记为“停止传播”，则不再继续处理。

示例：事件冒泡的简单实现

下面是一个简化的 Rust 代码示例，展示了如何通过返回值控制冒泡：

// 定义事件状态
enum EventStatus {
    Bubble, // 事件继续冒泡
    Stop,   // 事件停止传播
}

// 子组件的事件处理
impl ChildComponent {
    fn handle_event(&mut self, event: KeyEvent) -> EventStatus {
        if self.inputting { // 假设 inputting 是子组件的一个状态
            // ... 处理输入逻辑 ...
            // 如果正在输入，我们消耗了 'q' 键，不希望它冒泡去触发退出
            if event.code == KeyCode::Char('q') {
                self.buffer.push('q');
                return EventStatus::Stop; // 消耗事件，停止冒泡
            }
            // ... 其他输入处理 ...
            EventStatus::Stop // 通常输入组件会消耗大部分按键事件
        } else {
            // 如果不在输入模式，可能某些键对子组件无意义，允许冒泡
            if event.code == KeyCode::Char('j') {
                 // 子组件处理了 'j' 键，并决定停止冒泡
                self.scroll_down();
                return EventStatus::Stop;
            }
            EventStatus::Bubble // 其他键允许冒泡
        }
    }
}

// 父组件的事件处理
impl ParentComponent {
    fn handle_event(&mut self, event: KeyEvent) -> EventStatus {
        let mut child_status = EventStatus::Bubble; // 默认允许冒泡

        // 根据焦点将事件传递给子组件
        if self.focus == Focus::ChildInput { // 假设 focus 指向子组件
            child_status = self.child_input.handle_event(event);
        }
        // ... 可能还有其他子组件 ...

        // 如果子组件要求停止冒泡，则父组件也停止
        if matches!(child_status, EventStatus::Stop) {
            return EventStatus::Stop;
        }

        // 若事件从子组件冒泡上来 (child_status == EventStatus::Bubble)
        // 父组件现在可以处理这个事件了
        if event.code == KeyCode::Char('q') {
            // 父组件处理 'q' 键，例如退出应用
            self.should_quit = true;
            return EventStatus::Stop; // 父组件消耗事件
        }

        EventStatus::Bubble // 如果父组件也不处理，事件可以继续向上冒泡（如果还有更上层）
    }
}

通过精心设计事件的向下传播（基于焦点）和向上冒泡（基于事件处理的返回值或状态标记）机制，我们既实现了“组件化”来复用代码和分解复杂度，又给每个组件留下了非常大的自由度。每个组件只需要实现一个至少能表明事件传播状态（如返回 EventStatus）的 handle_event 方法即可。

这是一个相对低级别的抽象，它允许每个组件根据自身需求自由地实现其内部逻辑。如果组件逻辑简单，一个 match 表达式可能就足够了；如果组件内部状态转换复杂，它甚至可以在其内部再使用 TEA 架构来管理。

更进一步，事件处理的返回值也不必局限于 EventStatus。例如，一个输入组件的 handle_event 方法，除了返回 EventStatus 外，还可以返回一个 Option<String>。当用户在输入组件中完成输入并提交时（比如按下回车），它就可以返回 (EventStatus::Stop, Some(entered_text))，父组件据此可以获取到输入结果。

更进一步：构建多页面 TUI 程序

当我们掌握了组件化的事件处理之后，构建一个多页面的 TUI 应用也就水到渠成了。

问：如何从组件化的程序出发，实现一个多页面的程序？
答：可以将每一个“页面”也视为一个大型的、独立的“页面组件”。然后，让应用的根组件（或一个专门的页面管理器组件）负责根据当前应用状态来渲染和切换这些页面组件。这样，根组件就扮演了页面调度器的角色。

问：如何实现“返回上一页”功能，并且保留上一页面的状态？
答：一个常见的做法是在根组件（或页面管理器）内部维护一个栈（Stack）。这个栈里存储的不是完整的页面组件实例（这可能涉及复杂的生命周期和状态复制），而是能够重建页面组件的“关键状态”或页面标识。

当打开一个新页面时，可以将当前页面的关键状态压入栈中，然后展示新页面。
当需要返回上一页时（例如用户按下 ESC 键或），就从栈中弹出顶层元素，并根据弹出的状态/标识来恢复并渲染上一个页面。
当前显示的页面总是对应于栈顶的元素。

问：页面组件如何通知根组件（或页面管理器）进行页面操作，如打开新页面、切换到特定页面或关闭当前页面？
答：这涉及到组件间的通信。一种有效的方式是使用异步消息传递通道，例如 Rust 中 tokio::sync::mpsc 模块提供的 unbounded_channel（如果你的 TUI 应用是异步的）。

根组件（或页面管理器）持有一个消息通道的接收端（Receiver）。
当创建每个页面组件时，给它一个该消息通道发送端（Sender）的克隆副本。
当页面组件内部发生某个动作，需要触发页面导航时它就通过自己持有的 Sender 发送一个预定义好的消息给根组件。
根组件在其主事件循环的每一轮迭代中，除了处理用户输入事件外，还会尝试从消息通道中读取这些页面导航请求，并据此更新页面栈和当前显示的页面。

Rust 适合用来做 TUI 吗？

最后，我们来聊聊选择 Rust 来开发 TUI 应用的一些考量。除了 Rust，像 Golang、Python、JavaScript 等语言也都有其活跃的 TUI 开发社群和不错的库。

Golang 的优势包括：

更完善的生态：例如 BubbleTea 库，它不仅提供了 TEA 架构的实现，还有大量预置的组件和活跃的社区。
自带垃圾回收：UI 应用中的状态和组件生命周期管理往往比较复杂，GC 可以在一定程度上简化这方面的心智负担。
一次编译，到处运行：Go 优秀的跨平台编译能力。

Rust 的优势则在于：

相对更快、更安全。
语言本身更加现代。

除了这些原生编译型语言，Python 和 JavaScript 的生态较 Rust 相比也更加完善，而他们的性能在绝大多数 TUI 场景下也是足够的。

可以看出，Rust 其实在 TUI 领域没有什么特别的优势，但是，近年来 Rust在 TUI 领域的关注度也在逐渐提升。例如，微软使用 Rust 开发了其终端编辑器 Edit，OpenAI 也使用 Rust 和 ratatui 构建了其 Codex CLI 中的 TUI 部分。随着这些大公司的投入和成功案例的出现，我们可以期待 Rust 的 TUI 生态会变得越来越完善和强大。

总结

回顾本次的分享，我们探讨了 TUI 事件处理的几个关键方面：

事件处理是 TUI 开发中复杂度的主要来源：它不像 UI 渲染那样有成熟的库可以完全代劳。
TEA 架构是一种能够很好地处理复杂状态更新的模式：通过 Model-Update-View 的分离，使得逻辑更清晰。
对于更大型的应用，组件化是管理复杂度和复用代码的有效方法：将应用拆分为独立的、可复用的组件。
组件化引入了事件传播的新问题，需要妥善处理事件的向下传播和向上冒泡：
- 向下传播通常可以通过在父组件中维护一个 focus 状态来实现，指明当前哪个子组件接收事件。
- 向上冒泡可以通过事件处理函数的返回值（如 EventStatus::Bubble 或 EventStatus::Stop）或事件对象自身的状态来控制，允许子组件决定事件是否继续向上传递。
多页面 TUI 程序可以通过将每个页面视为一个独立的组件来实现，并使用栈来管理页面切换和状态恢复。

Astro (Vite) 中将字体作为 ArrayBuffer 导入

Mon, 09 Dec 2024 03:37:17 GMT

TIP: 在 RSS 阅读器中，一些组件可能无法正常显示。在浏览器中打开以获得更好的阅读体验。

这些天正在折腾自动生成 OG Image，会需要把字体作为 ArrayBuffer（或者 Node.js 的 Buffer）导入的情况。尝试了一番，在 Vite 中终于找到了一个我认为还不错的解决方案。

TL;DR 写个小 Vite 插件实现导入文件的绝对路径，然后用 fs 读入。

需求详情

虽然很久之前就知道 vercel/satori: Enlightened library to convert HTML and CSS to SVG 这个库了，但是一直拖着没做自动生成 OG Image 的功能，这两天下定决心按照 liruifengv 的文章 Astro 自动生成 Open Graph & Twitter card 图片😄 | liruifengv 把这个功能做出来。

首先，我的需求是在构建时生成 Image，没在实时 SSR 上试过（但感觉应该没问题？）；同时，需要是个 ESM 的解决方案，不要用到 require 。在这之中遇到的最重要的问题就是 satori 需要一个字体的 ArrayBuffer 来做渲染，也是我踩了不少坑的地方。

Vite 在 dev 和 build 时文件和文件之间的相对路径不同，因此需要一个使用 import 语句的方法，让 Vite 寻找对应的文件
如果使用网上找到的将字体直接导入的方法（其实是将字体读入 Buffer 之后转成 base64， export default 出来），会爆内存，因此需要使用 fs 模块亲自读文件
原文章里的通过 fetch 网站地址的方案感觉怪怪的 🤐 希望有个不依赖“是个网站”的方法

踩坑过程

首先，当然是看看参考的文章里是怎么干的。复制一小段：

const isDev = import.meta.env.DEV;
const website = isDev ? "http://localhost:4321/" : SITE.website;

const fetchFonts = async () => {
  const fontFileRegular = await fetch(
    `${website}fonts/ZCOOL_KuaiLe/ZCOOLKuaiLe-Regular.ttf`
  );
  const fontRegular: ArrayBuffer = await fontFileRegular.arrayBuffer();
  return { fontRegular };
};

const { fontRegular } = await fetchFonts();

呃 🤔……感觉有点黑魔法，有硬编码的 dev server 路径，感觉不太对；而且如果是 production build 的时候会保证是从 public 文件夹里读取而不是上一次部署的网站里吗？看了一圈 Astro 的文档，也没找到像这样的用法。所以打算找个更“一般”（至少 Vite 项目通用）的办法。

下一步，我知道 Vite 可以做到直接 import 一些二进制文件，这一般是通过某些插件实现的。因此，打算使用一个 Vite 插件可以直接将 ttf 文件导入成一个 ArrayBuffer。

很轻松就能找到这样的插件，比如 vite-plugin-arraybuffer 或者直接用了 satori 做例子的 unplugin-font-to-buffer 。但是实际运行中会出问题——会直接爆内存。查看这些插件的实现，可以发现它们简单地用 fs 将这些文件读进来，序列化之后 export default 出去。然而，可能因为需要生成很多个图片，所以被导入了很多次，然后就爆内存了。

[!NOTE] 我的环境：Node.js 22 和 Vite 6 (Astro 5)，运行在 macOS arm64 上。其他环境会不会爆内存未知。

之后通过简单的测试，我发现自己调用 fs 读文件而不是在 Vite 插件里读文件不会爆内存，因此显然只能这么干了。

无论是 node 的 fs 还是其他 JS 运行时提供的 fs 包，都需要提供一个路径。最朴素的想法当然是直接用当前文件和字体文件的想对路径。

然而，Vite 在 dev 和 build 之间的文件相对路径并不一致，比如一个 dev 环境中存在于 utils/a.ts 文件中的 fs 调用，在 build 环境中会先被打包进 pages/index.mjs 然后才被调用，同时字体文件也会被打包并且加上 hash 后缀，这时候显然就找不到文件了。

如果不想用黑魔法（比如逐级往上读文件目录直到项目根，然后再从项目根找字体文件）的话，还是得依靠 Vite 的 module resolve 来获取路径。

这时，如果对 Vite 比较熟悉的话，会想到 Vite 自带的 "path?url" 导入，可以获取一个路径。然而，这样获取的是一个相对于项目根目录的路径，但是 fs 模块并不知道项目根目录是哪个 😢，我搜查了一番也没找到怎么获取项目根目录的绝对路径。

但是，我们是可以做到 import 时获取绝对路径而不是相对路径的，因为 Vite 插件可以获取文件的绝对路径（或者是可以被 fs 正确读取的想对路径），只要把这个路径放回回来即可。

解决方案

[!NOTE] 如果在使用作为 ArrayBuffer 导入的方案不会出现内存问题的话，我还是推荐直接导入，更加直观。

首先写一个小插件：

function fileSystemPath() {
  return {
    name: "vite-plugin-file-system-path",
    transform(_: unknown, id: string) {
      if (id.endsWith("?filepath")) {
        return {
          code: `export default ${JSON.stringify(id.slice(0, -9))}`,
          map: null,
        };
      }
    },
  };
}

然后把它放进 Vite 插件列表里。对于 Astro，可以在配置的 vite.plugins 中添加它。参考

其次，添加类型声明。找一个没有导入导出的文件（或者直接用一个 .d.ts 文件），添加下面的声明：

declare module "*?filepath" {
  const value: string;
  export default value;
}

使用：

import fontPath from "@assets/fonts/SarasaUiSC-Regular.ttf?filepath";
const fontBuffer = await fs.readFile(fontPath);

Deploy with Workers 按钮使用指南

Tue, 15 Oct 2024 20:57:21 GMT

TIP: 在 RSS 阅读器中，一些组件可能无法正常显示。在浏览器中打开以获得更好的阅读体验。

为开发者和使用者而写的指南。需要使用该按钮的用户请看使用一节，需要设置该按钮的开发者请看开发一节。

由于 Cloudflare Workers 的特殊性，该按钮无论是使用还是设置起来都比 Vercel 的按钮复杂多了，而且文档也语焉不详，所以特地写了一篇文章。

写于 2024 年 10 月，如果之后流程有变请评论通知我修改。

[!WARNING] 2025-05-06 更新：

现在 Cloudflare 已经更改了按钮的使用方式，新的使用方法稍微用户友好了些，但是也有些 quirk。
因此，现在本文章已经过时，有空时我会更新本文章。

使用

为这个样子的按钮提供的指南。

开始之前

需要有一个 GitHub 账号。

最好提前注册好一个 Cloudflare 账号（如果没有，会在部署过程中提示注册）。

Authorize GitHub with Workers

没啥可说的，点击按钮后在 GitHub 授权即可。

Configure Cloudflare Account

这步比较复杂。

首先登录/创建一个 Cloudflare 账户。

下一步中， Account ID 按照它的指引（点击链接）后可以直接找到，很方便； API Token 略微复杂一些，下面细说。

首先点击它提供的 My Profile 链接，这个链接应该会直接指向 API Tokens 这个页面（如果没有，先登录，然后重新点击这个链接）

点击 Create Token 按钮；

选择 Edit Cloudflare Workers 这个 template

然后下一个界面里，

修改 Token name （不必要但推荐）
Permissions 不需要修改
Account Resources 和 Zone Resources 都选 Include All 就行
TTL 可以不管

Continue to Summary 然后 Create Token。

复制此时显示的 Token，然后返回 Deploy Button 的网页填入。

Deploy with GitHub Actions

这里跟着指引应该很轻松。

先点下按钮，会自动 Fork Repo（此时 Repo 中会自动创建数个 CF 相关的 Action Secrets）
按照指引前往（点击链接）前往 GitHub 启用 GitHub Actions
最后点击 Deploy 按钮，等待一段时间（一般就几分钟）让 GitHub Actions 跑完就部署好了。

如果 GitHub Actions 报错，请联系仓库原主人，有可能是他的 GitHub Actions 配错了/没有为 Fork 的仓库考虑。

开发

Cloudflare 有一篇文档，但是年久失修，且不全。https://developers.cloudflare.com/workers/tutorials/deploy-button/。所以才写了本文。

我的一个使用了该按钮的例子： yy4382/read-aloud: 运行于 Cloudflare Workers 上的微软“大声朗读”转发器。通过简单的 HTTP GET 请求，将文本转换为语音。

原理

这篇教程适用于使用 wrangler 进行部署的 Cloudflare Workers 项目，比如 Hono 项目。

Deploy with Cloudflare 按钮的基本原理是帮用户 Fork 你（开发者）的 Repo，然后使用 Repo 中的 Actions 部署 Worker 到 Cloudflare 中。

而由于这个按钮会帮助用户 Fork，因此作为开发者需要做的就是设置一个 GitHub Actions，可以在任何仓库中进行部署。

设置 Actions

首先，需要保证你的项目可以直接通过 wrangler deploy 命令（不带其他选项）进行部署。需要注意的是，如果是 Hono 创建的项目，可能需要在 wrangler.toml 中增加 main 属性指定入口文件（一般是 src/index.ts[x]）。

然后添加 .github/workflows/deploy.yml，以下是我推荐的一个例子

name: Deploy Worker
on:
  push:
    branches:
      - main # trigger deploy everytimes pushed to main
  repository_dispatch: # The deploy button relies on this line to work
  workflow_dispatch: # gives you a button to manually trigger job
  
jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v2
      - name: Build & Deploy Worker
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CF_API_TOKEN }}
          accountId: ${{ secrets.CF_ACCOUNT_ID }}
          # workingDirectory: # required if your wrangler.toml is not in root dir
          # See https://github.com/cloudflare/wrangler-action for more options

可以发现，使用了 CF_API_TOKEN 和 CF_ACCOUNT_ID 两个 secret，作为开发者需要手动设置（在 GitHub Actions 中使用机密 - GitHub 文档），而你的用户通过 Deploy with Cloudflare 按钮 Fork 时会被自动设置好。

然后尝试手动运行该 Action，确定可以正常运行。

插入按钮

将 [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/YOURUSERNAME/YOURREPO) 中的 YOURUSERNAME 和 YOURREPO 替换一下之后就可以放在任何 Markdown 文档里了。

SVG 签名动画初探

Sun, 04 Aug 2024 06:00:45 GMT

TIP: 在 RSS 阅读器中，一些组件可能无法正常显示。在浏览器中打开以获得更好的阅读体验。

发现 Anthony Fu 写的这篇 Animated SVG Logo，可以通过 SVG 和 CSS 动画实现动态的签名效果；后来又看到了 Innei/Shiro 主题用了这样的签名效果来在版权卡片上面签名，感觉很有意思，于是自己把两者结合，用 Anthony 的方法制作了图标，实现了 Innei 中图标的功能……

这篇文章是个简单的教程/记录，希望能帮助到你。

目前你可以在本站每篇文章尾部的 Copyright 卡片上看到这个动态签名。

[!TIP] 如果你正在 RSS 阅读器中阅读这篇文章，可能无法看到上面图标的动态效果（甚至只能看见一片白），建议在浏览器中查看。

原理简析

假设现在我们有一个“一笔画成”的 SVG 文件，我们可以通过控制这“一笔”显示的部分有多长来实现动画效果，而 CSS 的 stroke-dasharray 属性正好可以做到这一点。

但是，很多名字是不能“一笔画成”的，这也是不少人放弃这个方法的原因，但是从 Anthony 的文章中我们得到一个新方法：使用一个遮罩来遮住多余的部分。他在文中使用这个方法是为了笔画的粗细变化，但是只要把遮罩的形状设置得合适，我们也可以用这个方法来实现“一笔画成”的效果。

更具体的细节，可以前往 Anthony 的文章查看。

至于 Innei/Shiro 主题中的效果，其实并不像签名，而是“逐渐显示”。这个制作起来会方便很多，如果你只想要一个简单的动画效果，而不是一定要“签名”动画，可以查看制作一个好看的动态签名🖋️ - 柃夏chapu。

实现步骤

画图标

在 Google Fonts 中选一个自己喜欢的字体；
在 https://danmarshall.github.io/google-font-to-svg-path/ 中下载为 SVG 文件
将 SVG 文件导入 Figma
用钢笔工具跟着线路“一笔画”画出签名（中间不连续的地方可以先直接连上，比如下图 i 的竖杠和圆点之间）

[!TIP] 这步应该是最难最烦的，尤其是对于不熟悉 Figma 的人，可以自行搜索怎么用 Figma 的钢笔工具
也可以尝试把我画好的签名导入 Figma，看一看是怎么操作的。
画一个可以遮住多余部分的图形（如果需要）
将遮挡图形设置为 Mask
想要线条粗细变化？方法是加遮罩，和上文提到的遮住多余部分一个道理，把粗的线遮细点……
导出这个 SVG 文件

放入项目

导入你的项目中，不同框架导入方式不同，比如我用 Astro，可以这样：

// signature.astro
---
import Sign from "@assets/signature-yunfi.svg?raw";
---
<div class="float-right signature-wrapper">
  <Fragment set:html={Sign} />
</div>

设置 CSS，可以参考 antfu 文章中的写法

最好去 SVG 文件里给主要的 path 加上 id（我加的是 main-stroke），方便 CSS 进行 query
--signature-length 属性是主要笔画的长度，最好通过二分法试一试，如何太大，动画看上去会很快，如果太小动画会从笔画上的好几个地方一起开始播放。

/* 使用了带有 nested 支持的 Tailwind CSS，如果你没用的话，需要自己写 */
.signature-wrapper {
  --signature-length: 2550px;
}
/* https://antfu.me/posts/animated-svg-logo */
.signature-wrapper #main-stroke {
  @apply stroke-black dark:stroke-white opacity-100;
  stroke-dashoffset: 1px;
  stroke-dasharray: var(--signature-length) 0;
  animation: grow 7s ease-out forwards infinite;
  transform-origin: center;
  animation-delay: 0s;
}
@media (prefers-reduced-motion) {
  path {
    animation: none !important;
    stroke-dasharray: unset !important;
  }
}
@keyframes grow {
  0% {
    stroke-dashoffset: 1px;
    stroke-dasharray: 0 var(--signature-length);
    opacity: 0;
  }
  10% {
    opacity: 1;
  }
  45% {
    stroke-dasharray: var(--signature-length) 0;
  }
  /* Moving back */
  65% {
    stroke-dasharray: var(--signature-length) 0;
  }
  95%,
  to {
    stroke-dasharray: 0 var(--signature-length);
  }
}

大功告成！

参考

Debounce 与 Throttle：作用和区别

Wed, 17 Jul 2024 03:49:29 GMT

TIP: 在 RSS 阅读器中，一些组件可能无法正常显示。在浏览器中打开以获得更好的阅读体验。

lodash 和其他很多工具库（比如 VueUse）都有 debounce（防抖）和 throttle（节流）的概念。简单（且有点不严谨）地讲，如果事件一直被触发，debounce 之后在最后停下来之后处理它，而 throttle 会每隔一段固定时间去处理它。

[!NOTE] 在本文中我“刻意地”没有加入任何一行代码，因为发现在阅读别人的相关文章学习时，他们给出的大段代码并没有很好帮助我理解，反而是一些概念原本可以用自然语言说清楚，却非要让读者读代码来理解，造成了一个很大的 friction。如果你是那种喜欢看代码来理解的人，可以直接看 lodash 的 Debounce 源码和 Throttle 源码, 或者在参考阅读中找篇文章看。

防抖和节流确实是非常常见和基础的东西，有能搜到的相关文章多如牛毛，我也一直在犹豫要不要吧本文发出来。最后发现本文和其他文章还是有“无代码”这个差异点，于是选择了发布。

Debounce

先从 Debounce 说起吧。一般我们把 Debounce 翻译为防抖，通常用于处理用户的文本输入。

Debounce 一个比较正式的定义来自 lodash 的文档：

Creates a debounced function that delays invoking func until after wait milliseconds have elapsed since the last time the debounced function was invoked.

这里涉及到了两个函数，第一个是原本的、需要被防抖的函数 F，第二个是 _.debounce 函数返回的、防抖过的函数 F'。这段定义就是只有在最后一次 F' 被调用若干时间后才会调用 F。如果在等待这“若干时间”里 F' 又被调用了，那么这次的调用就变成了“最后一次”，所以需要重新等待。

上面的解释还是有点抽象，用很简单的说法来说，就是如果不停的调用 F'，那么真正的函数 F 不会被调用，直到对 F' 的调用停下来若干时间之后。用常见的输入框防抖来说，如果 wait 被设置成了 300 ms，那么如果用户一直以 200 ms 的间隔输入字符，那么函数一直不会被调用，直到用户停止输入（300ms）之后，F 才会被调用。

这时候看 lodash debounce 的参数， wait 的含义应该不用多说；剩下还有 maxWait 和 leading & trailing。这篇文章里我不打算深入研究 leading 和 trailing，感兴趣的可以看这篇文章，至于 maxWait，则是如果一直在等待的话，最多等 maxWait 毫秒就要调用一次。还是拿上面的输入框例子来说。如果设置了 maxWait 为 1000 ms，那么假如用户一直不停地输入了整整 5 秒钟，那么函数会在 1、2、3、4、5 秒后分别调用一次，因为它“最多只能等”1000ms；而如果没有 maxWait，则只会在 5s + 300ms 后调用 1 次。

Throttle

Throttle 有些人翻译成“节流阀”，但是我觉得这里应该是用动词“节流/减速” 更好，和“防抖”相对。一般来说用来处理 Resize 或者 scroll 事件。

如果你理解了 Debounce 和它的 maxWait 参数，理解 Throttle 应该是易如反掌的。先看 lodash 的定义：

Creates a throttled function that only invokes func at most once per every wait milliseconds.

也就是说，如果一直调用，那么真正的函数每 wait ms 触发一次。

有没有感觉和 debounce 的 maxWait 有点像？实际上，_.throttle 就只是 _.debounce 的一个简单包装，将 debounce 的 maxWait 设置得和 wait 一样，就得到了一个 Throttle 函数！如果感兴趣，可以看这不到20行代码的实现

和 Debounce 一样，如果你对 leading 和 trailing 参数感兴趣，可以查看这篇文章

参考阅读

Debounce vs Throttle: Definitive Visual Guide

Throttle & Debounce behavior (lodash)

Debouncing And Throttling Explained Through Examples | CSS-Tricks

Lodash Documentation Throttle Debounce

useDebounceFn | VueUse useThrottleFn | VueUse

把 S3 ( R2 / OSS / COS ... ) 作为图床使用的图片管理方案

Sat, 27 Apr 2024 17:00:33 GMT

TIP: 在 RSS 阅读器中，一些组件可能无法正常显示。在浏览器中打开以获得更好的阅读体验。

最近，成功的把我的图床搬迁到了 Cloudflare 的 R2 上，并写了个类似图床前端的管理工具。R2 是一个兼容 S3 协议的服务，因此，如果你有兴趣使用 Cloudflare R2 / Amazon S3 / 阿里云 OSS / 腾讯云 COS 来托管你的图片，我编写的这些工具对你也有用。关于为什么迁移到 S3，请看为什么用 S3 这个小标题，希望你看后也能考虑一下。

[!TIP] 如无特殊说明，下文的 "S3" 均指各种兼容 S3 的服务。

如何把 S3 当作图床？

一般来说，只要开启 S3 bucket 的公共访问权限即可。同时有些服务支持自定义域名，而不是使用 endpoint 的 url。

图片直接放进 S3 里即可，虽然不是必要的，但我还是推荐按照日期分文件夹，日后管理起来会相对方便一些（包括我的工具默认上传也是以日期分文件夹的）。

[!TIP] 对于 Cloudflare R2，如果绑定了自己的域名，可以在域名那里设置 Cache Rule，设置得长一点（一般没有人会更改已经上传的图片吧🌚），这样几乎就可以拥有无限次访问操作的额度了。

管理 S3 中图片的工具——S3 Image Port

传统的图床一般都有一个管理面板，但是 S3 一般没有（至少没有专门用来管理图片的）。因此，我自己写了一个前端面板： yy4382/s3-image-port。

我在 Vercel 上托管了一个公共实例 https://iport.yfi.moe，各位可以在 Settings 标签页中输入信息后直接使用。虽然代码开源且不会上传任何信息到服务器，如果你实在不放心，也可以 fork 之后自己部署到 Vercel 甚至是自己的服务器——面板可以是纯客户端渲染的，因此可以静态部署。

功能

上传照片（包括上传前转换格式）
展示图片列表
复制图片链接（包括 markdown 格式的）
删除图片

界面展示

上传页面：

图片列表：

同时，它在手机上也能完美地加载展示。

使用说明

现在，它有自己的文档页了！S3 Image Port Docs

使用前需要在 Settings 标签页下填写 S3 的 endpoint、储存桶名称和地区，还有两个密钥。还有一些可选的高级选项，比如如果 S3 储存桶开启了自定义域名，则可以通过 public url 设置复制的链接的格式。

至于 S3 相关密钥的获取，请参照各个服务的文档，比如 R2 的就在 Manage API Tokens 链接中。值得一提的是，R2 会给一个叫 "Token value" 的东西，它是 Cloudflare 自己的东西，我们需要的是下面给的 Access Key ID 和 Secret Access Key。

使用反馈

如果有使用上的疑问/发现了 bug，请在 GitHub 上发 issue。

如果需要新功能，也请直接在 GitHub 上发 issue！只要不是太离谱，我都会抽时间做的。

如果你恰好也会编程，并且已经写了一些新功能，非常欢迎 PR！

当然，直接在本文下方评论或者在各个平台上找我也行。

为什么用 S3 (R2)?

关于为什么选择 S3 （其实是兼容 S3 的 R2 ）作为我的图床，我原本写了一大堆理由，但是现在才想起我的初衷：完全的可自定义的域名和路径。无论你之前使用的是什么方案，迁移到 S3 和它的兼容服务都是几乎无障碍的。

因为我已经在很多地方使用了类似 https://i.yfi.moe/i/2024/04/19/2cm1jl.webp 这样的图片链接，如果只是更改了域名 i.yfi.moe，我还可以用重定向之类的方法简单的处理下，如果连路径 /i/2024/04/19/2cm1jl.webp 都变了，那么维护一个新旧路径的重命名实在是过于麻烦。

因此，我需要能够随意设置一张图片的路径，最好域名也是可以自定义的。因此，绝大部分的图床托管方案都被 Pass 了，因为（至少我还没找到）可以自定义图片路径的托管服务；而一部分带数据库的自建服务（比如 Lsky Pro）因为没法自定义路径（可以设置上传时的路径格式，但是没法改已经上传的图片的路径）也被 Pass，剩下的就只有一些类似 EasyImage 这样的依托文件系统路径而非数据库的自建图床，或是 S3 这类服务了。

[!NOTE] 当然，如果你原本使用的而是托管服务，设置从他们的域名到新域名的重定向往往是不现实的。但是如果你的图片使用大都实在同一个项目（或少数几个项目里），可以方便的通过 VSCode 提供的项目级别查找替换（在左侧栏上的搜索图标）来轻松地将所有就域名替换为新域名，同时保持路径不变。

我原本在很长一段时间内使用的都是 EasyImage，但主要有两个痛点：

自建的图床，虽然对数据有完全的主导权，但是可能因为各种服务器管理上的问题出现服务不可用甚至是丢数据的情况。虽然在过去的一年多我达成了图床 100% SLA，并且从来没有丢过数据，但是心理总是慌慌的。对比来说，虽然 Cloudflare 对免费用户没有 SLA 保证，但是可以让自己少很多心智负担。（而且真出问题了也能甩锅🤣）
它是用 PHP 写的，虽然 PHP 是世界上最好的语言（误），但是我不会写 PHP，想改点东西总是束手束脚的。

此外，我迁移到 R2 的理由还有：

真的很便宜。以我的使用量几乎就是免费用。
如果使用自己的域名，在国内的访问速度也还凑合。而且等我自己的国内域名 yunfi.top 备案通过之后，可能会把国内的访问分流到腾讯云的 COS。而 R2 和 COS 之间可以随便找台 VPS 跑 rclone 来同步。

Yunfi Blog

更快地初始化 Shiki 代码高亮

问题

按需加载

效果

参考

在 Markdown 中使用 React 组件

需求

Markdown 如何包含 React 组件？

欠优化的方法

方法一：RSC 就是为此而生的

方法二：手动 SSR + hydrateRoot

思路实现

缺陷

方法三：将 HAST 传到客户端

效果展示

复制按钮

GitHub 仓库信息卡片

注

为什么不用 MDX？{#why-not-mdx}

Footnotes

Rust TUI 事件处理：从 TEA 到组件化

TUI 程序是如何运作的？

TUI 开发的核心任务

TEA 架构：一种优雅的事件处理模式

示例：一个简单的 TODO 应用

Model (状态):

Action (操作):

Update (更新逻辑):

Event 到 Action 的转换:

当应用逐渐变大：组件化

组件化带来的事件处理新挑战

1. 事件的向下传播：哪个组件来响应？

2. 事件的向上冒泡：子组件如何影响父组件或全局？

控制事件冒泡：

示例：事件冒泡的简单实现

更进一步：构建多页面 TUI 程序

Rust 适合用来做 TUI 吗？

Golang 的优势包括：

Rust 的优势则在于：

总结

Astro (Vite) 中将字体作为 ArrayBuffer 导入

需求详情

踩坑过程

解决方案

Deploy with Workers 按钮使用指南

使用

开始之前

Authorize GitHub with Workers

Configure Cloudflare Account

Deploy with GitHub Actions

开发

原理

设置 Actions

插入按钮

SVG 签名动画初探

原理简析

实现步骤

画图标

放入项目

参考

Debounce 与 Throttle：作用和区别

Debounce

Throttle

参考阅读

把 S3 ( R2 / OSS / COS ... ) 作为图床使用的图片管理方案

如何把 S3 当作图床？

管理 S3 中图片的工具——S3 Image Port

功能

界面展示

使用说明

使用反馈

为什么用 S3 (R2)?