10KB前端轻量运行时colibri：蜂鸟式性能优化设计

1. 项目的来龙去脉：colibri 这个名字不是随手起的

做了近一年的移动端性能优化，我对"轻量"两个字的执念越来越深。为了在弱网、低端安卓机上拿到理想的首屏和交互指标，我自己维护了一个叫 colibri 的前端轻量运行时。colibri 把渲染、状态管理、事件处理三个核心能力压缩进 gzip 后 10KB 的产物里；如果你平时被活动页、营销页、工具页的性能问题困扰，而且不想每次都拖着一整套重型框架上线，这个项目的取舍思路值得你看一看。

先说一个很多前端团队都遇到过的场景：一个面向移动端的 H5 运营页面，活动马上要上线，需求方要求首屏秒开。你打开代码仓库一看，框架运行时、路由、状态管理、UI 组件库全部被打进了主包，gzip 之后还有 200 多 KB。用 DevTools 模拟 Slow 3G 测一遍，LCP 稳稳排在 6 秒开外。这时候你能做什么？拆包、懒加载、骨架屏、CDN 预热，能上的方案都上了，但框架本身的体积摆在那里，优化空间是有上限的。这种项目做多了，我开始认真琢磨一个问题：复杂中后台系统需要框架的生态和抽象能力，但纯展示型页面、活动页、轻量工具页真的需要把整套框架引进来吗？如果自己维护一套轻到极致、刚好够用的运行时，体积能压到什么程度，使用体验是不是还能保持顺滑？这个念头直接促成了 colibri 的第一行代码。

1.1 colibri 取的是蜂鸟的意思

colibri 是法语和西班牙语里对蜂鸟的称呼。蜂鸟最让人印象深刻的特征是什么？体型极小、翅膀振动频率极高、反应极其灵活，可以在空中悬停甚至倒退飞行。这三个特征恰好对应我对这个前端方案的期待：体积小、执行快、交互反馈足够灵敏。名字定下来之后，很多设计决策就变得好做了，凡是和"又重又慢"沾边的功能，砍掉的时候完全不心疼，因为蜂鸟本来就不需要大象的能力。

项目给自己定的硬指标是：整个运行时核心产物 gzip 后不超过 10KB。作为对比，常见重型框架的运行时通常在 30KB 到 80KB 之间，再加上配套的生态库，整体体积可能是 colibri 的几倍甚至十几倍。这个差距在最严苛的环境，也就是弱网、两年前的千元安卓机、老旧 WebView 里，会被用户直接感知。移动端优化有一条很多团队不太愿意面对的原则：每一个字节都是真实成本，框架本身的体积决定了性能优化的下限。

1.2 已经有了那么多轻量方案，为什么还要自己造

可能有人会问，Preact、Svelte、petite-vue 这些轻量框架已经很成熟了，为什么还要维护自己的方案？这个问题当时确实认真想过，答案其实很简单：我要的不是一个性能标杆，而是一个行为完全可控、没有任何历史包袱、刚好覆盖自己项目形态的运行时。

Svelte 非常优秀，但它的编译器在产物里仍然带了不少 runtime，对纯展示型页面来说这部分开销不必要。petite-vue 做了极小的形态，但它的模板语法和响应式模型从 Vue 继承而来，复杂度和抽象层还是偏多。相比之下，colibri 的定位不是又一个框架，而是一套可按需取用的前端轻量工具集。它不打算替代生态，而是在特定场景下成为比生态更合适的选择。也因此，colibri 项目里到处是"明确不做什么"的记录，这些记录的价值甚至比"做了什么"更高，因为它们才是体积和复杂度不失控的根本原因。

1.3 适合谁读、适合什么项目

如果你正在做内容展示型 H5、电商活动页、宣传落地页、小型工具应用，或者你在为一个"上线时间极紧但性能要求极高"的页面发愁，colibri 的思路会很有参考价值。相反，如果你维护的是复杂后台管理系统、大型电商平台，我反而建议你不要轻易参考这个方案，那不是它的战场。轻量方案的适用边界，和性能指标同样重要，判断一个技术方案好不好，永远要回到"放在什么场景里"这个前提。

2. 核心设计：10KB 内装下什么，取决于砍掉什么

设计一套轻量方案，难点不在"加功能"，而在"定边界"。colibri 从第一天起就明确了自己的能力边界：不做虚拟 DOM、不做完整的组件生命周期、不做跨端编译、不做 SSR。这四个"不做"，基本保证了体积不会失控。

那保留了什么呢？在我看来，前端运行时最核心的诉求无非三块：事件处理、状态管理、视图更新。colibri 的所有功能都围绕这三个核心模块展开，每个模块只解决一个特定问题，模块之间用一个极简的核心调度器串联，避免层层抽象带来的额外开销。下面逐个讲清楚。

2.1 砍掉虚拟 DOM 之后的渲染策略

把 colibri 推荐给同事时，听到最多的质疑是：没有虚拟 DOM，更新性能会不会崩？实际上，在内容展示型页面里，真正需要高频更新的 UI 组件非常有限，计数器、切图、滚动加载状态、表单校验提示，这些场景下的 DOM 操作量本身很小。虚拟 DOM 的 diff 优势在这里根本发挥不出来，反而要为它付出额外的对象创建与对比开销，这是一笔纯粹的负资产。

colibri 采用按模块粒度的脏检查配合直接 DOM 操作。状态变更时，只有订阅了对应状态切片的视图会重新执行渲染函数；渲染函数用模板字符串产出新结构，一个 mini diff 负责更新变更部分。这个 diff 只做两件事：判断文本内容是否变化、判断节点是否存在，不做递归的组件树比对。代码量很少，但已经覆盖内容页 90% 的更新场景。

function updateView(container, newHTML) { const tmp = document.createElement('template'); tmp.innerHTML = newHTML.trim(); const newNode = tmp.content.firstChild; if (!container.firstChild) { container.appendChild(newNode); return; } const oldNode = container.firstChild; // 只比较文本内容，不深入比对子节点结构 if (oldNode.textContent !== newNode.textContent) { oldNode.textContent = newNode.textContent; } // 属性变化用 attributes 遍历做单层对比 const oldAttrs = Array.from(oldNode.attributes || []); const newAttrs = Array.from(newNode.attributes || []); oldAttrs.forEach((attr) => { const target = newAttrs.find((item) => item.name === attr.name); if (!target) oldNode.removeAttribute(attr.name); }); newAttrs.forEach((attr) => { if (oldNode.getAttribute(attr.name) !== attr.value) { oldNode.setAttribute(attr.name, attr.value); } }); }

这套策略在 60 FPS 滚动的场景和频繁点击的场景下都验证过。最后定位到的性能瓶颈从来不在视图更新，而在图片解码、布局同步计算这些浏览器底层环节，跟框架本身关系不大。这也解释了为什么很多前端性能问题换个框架并不能真正解决，真正吃性能的往往是网络请求和渲染管线里更底层的东西。

2.2 事件系统：委托是起点，隔离才是重点

colibri 的事件系统基于一个简单的观察者模式，但在这之上做了两个关键设计。第一个是把事件监听尽可能上移到 document，用事件委托统一处理，减少内存里监听器的数量。第二个是给每个视图实例维护独立的命名空间，页面切换时调用一个offAll()就能把当前页面注册的所有监听全部清理，避免长运行页面里的内存泄漏。

实际开发里，事件泄漏是最隐蔽的问题。很多页面明明功能都正常，用户在使用过程中却感到越来越卡，多半就是退出页面时没有把定时器、滚动监听、全局事件清理干净。colibri 在页面根容器上记录所有 handler 引用，销毁时统一移除，同时内部还有一道保险：对高频事件做了自动节流，避免极端触发条件下监听器反复执行。

const registry = new Map(); const eventBus = { on(type, handler, el = document) { if (!registry.has(type)) { registry.set(type, []); // 统一走捕获阶段，配合 closest 命中数据属性 document.addEventListener(type, eventBus._dispatch, true); } registry.get(type).push({ handler, el }); }, off(type, handler) { const list = registry.get(type); if (!list) return; const idx = list.findIndex((item) => item.handler === handler); if (idx > -1) list.splice(idx, 1); }, offAll() { registry.clear(); }, _dispatch(e) { const list = registry.get(e.type); if (!list) return; list.forEach(({ handler }) => handler(e)); } };

事件机制保持得越薄，越不容易出问题。这也是一条值得记住的经验：底层代码的抽象层级，最好和它的功能复杂度保持在同一水平。过度设计的本质，就是用未来的假设来预支现在的复杂度，这在轻量项目里尤其致命。

2.3 状态管理：不需要 Redux，但需要明确的变更路径

状态管理模块没有做成 Redux 那样的完整实现，只提供createState和派生订阅。每个 Store 独立存在，组件通过 connect 辅助函数把 state 里的某个切片绑定到自己的渲染函数上。这部分的代码不到 30 行，但已经覆盖了绝大多数活动页的状态流转需求。

export function createState(initial) { let state = initial; const listeners = new Set(); return { get: () => state, set: (next) => { state = typeof next === 'function' ? next(state) : next; listeners.forEach((fn) => fn(state)); }, subscribe: (fn) => { listeners.add(fn); return () => listeners.delete(fn); } }; }

有人会问为什么不用 action 和 reducer。我的回答是：对内容页来说，后端接口返回的数据结构就是最自然的 action，正在变化的视图状态就是最自然的 reducer 结果。引入完整状态管理模式的维护成本，远大于它在这个场景下带来的收益。这是我特别想传达的一个观点：框架不是越完整越好，而是越贴合业务复杂度越好。复杂业务需要的是约束和规范，简单业务需要的是速度和直接。

3. 从原型到可用：实现过程中最费心思的几个点

colibri 从原型到可用，大概花了三个周末的时间。听起来不长，但中间反复推翻重来了三轮。每个模块单独拿出来都很简单，难的是把它们组合成一套没有别扭感的使用体验。这里挑几个卡过我的点详细讲，涉及模板、样式、构建和测试四个方向。

3.1 模板渲染与插值语法

渲染模块一开始用的是手写模板字符串拼接，页面一复杂就特别容易出错，某处少写了半个括号，整块内容白屏，错误信息还特别难以定位。后来改成插值语法{{ value }}，内部用正则做替换，支持变量和简单的三元表达式。改造之后模板可读性大幅提升，出错率也明显下降。

export function compile(tpl) { return function (data) { return tpl.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (match, key) => { try { return new Function('data', `with(data){ return ${key} }`)(data); } catch (e) { console.warn('colibri compile error:', key, e); return ''; } }); }; }

用with在严格模式下会直接报错，但这里用new Function包了一层，实际项目中明确规避严格模式即可。如果团队不接受这种写法，可以换成词法分析，但核心逻辑会增加几百行，对轻量目标不划算。模板编译的另一个细节是对输出值做安全格式化：null 和 undefined 统一输出为空字符串，对象输出 JSON 字符串，数字和布尔值按原始值输出。这个小改动让模板对后端不稳定的字段结构有很强的容忍度，不会在页面上渲染出 "undefined" 这种刺眼的字符串。

3.2 样式隔离：不编译、不哈希，靠约定

样式隔离没有用 CSS Modules，也没有用 Shadow DOM，这两者都有额外的兼容性或者运行时开销。colibri 的方案借鉴了 BEM 思想然后做了简化：每个组件指定一个根类名，内部所有样式都挂在根类名的后代选择器下。比如登录组件的根类是cl-login，内部按钮写成.cl-login .btn，表单写成.cl-login .input。

这里的坏处是 CSS 文件体积会变大一点，类名会变长，但好处非常实际：样式来源一目了然，审查元素时能直接看出它属于哪个组件；命名冲突天然被避免；不需要额外的编译步骤和哈希计算。对 10KB 的体积目标来说，省掉编译步骤和运行时开销是非常划算的交易。

在工程组织上，我还有一个强制约定：样式文件按照组件依赖深度从低到高排列，新写的样式一律使用与组件同名的类名前缀，禁止在组件内部写不带前缀的标签选择器。这套约定执行成本低，效果却比任何 CSS 工具都好，团队里的每个人翻起样式来都很快。

3.3 构建配置与体积控制

打包工具选的 esbuild。原因不是它时髦，而是同样压缩配置下它的产物体积比其他打包器平均小 5% 到 8%，而且构建速度极快，保存代码到构建完成几乎无感知。配合 terser 做二次压缩，再手动精简属性名，最终产物 gzip 后压到了 7.4KB。

这里补充一个不太被文档重视的细节：esbuild 的 tree-shaking 依赖 ESM 的静态结构，模块内部的具名导出确实能被正确剔除，但如果你引用了外部依赖，即使只用到其中一个工具函数，整个包的副作用也可能被保留。我的处理方式是在发布前人工审查产物体积分布，凡是贡献体积超过 1KB 的外部依赖一律重写成内部实现。自动树摇省不了的时间，就用人工审计来补，体积目标才不会失控。

npx esbuild src/index.js \ --bundle \ --minify \ --format=esm \ --target=es2017 \ --outfile=dist/colibri.min.js

3.4 测试策略：只测纯逻辑，不测浏览器

给前端运行时写单元测试，最怕的就是把测试写成浏览器兼容性测试，最后测出来的全是对浏览器 API 的重复验证。colibri 的测试策略很简单：核心的状态管理和事件系统在 Node 环境下用 Node 内置的 test runner 跑纯逻辑测试；渲染和 DOM 相关的代码不做单测，交给浏览器自动化测试覆盖。这样既不增加额外的 CI 依赖，又能保证真正容易出错的逻辑有回归保障。

这个策略现在回头看依然是对的。状态管理和事件系统的边界清晰、输入输出稳定，非常适合做单测；而 DOM 操作的行为太依赖于具体浏览器环境，硬写单测只会得到一堆意义不大的断言。测试的核心目的不是覆盖率数字，而是让回归成本可控。

4. 实测数据：在低端设备上把差距拉出来

理论说得再多，不如跑一组真实数据。我把一个实际的运营 H5 页面用 colibri 重构，和原来的 React 版本做了一轮对比。测试设备选的是 2019 年发布的千元安卓机，网络模拟用的 Chrome DevTools 的 Slow 3G，每一项指标都取三轮测试的中位数，避免偶然波动。

4.1 首屏加载与 LCP

同一个页面的两版实现，JavaScript 产物和核心性能数据如下：

数据差异最大的地方其实不是框架运行时本身的执行效率，而是请求数量。React 版的依赖链里带了几个按需加载的异步 chunk，每个 chunk 都是一次额外的网络往返，在 Slow 3G 下每次往返都可能是几百毫秒的延迟。colibri 把所有代码打进一个文件，请求数量压到最少，网络成本大幅下降。这也印证了一个容易被忽视的原则：移动端性能优化的杠杆，往往在网络层比在 CPU 层更大。很多团队盯着代码执行效率优化，却忽略了每一次多余的请求都在消耗用户宝贵的等待时间。

4.2 交互响应与内存占用

交互方面测了两个操作：一是长列表滚动，二是频繁开关带动画的侧边栏。React 版的滚动帧率在低端机上偶尔掉到 40 FPS，用户能明显感到顿挫；colibri 版基本稳定在 55 FPS 以上，滚动过程相对流畅。内存方面，连续 50 次进入退出同一个带动画弹窗的页面，React 版内存增长约 28MB，colibri 版约 6MB。这个差异主要来自事件监听清理和动画定时器回收机制的差异，colibri 的offAll()在页面切换时把所有监听和定时器引用一次清掉，框架事件系统的自动清理机制做不到这么彻底。

需要说明的是，这不是在说 colibri 比 React 更好。React 的生态完整度、团队熟悉度、组件复用性在复杂业务中优势明显，colibri 的价值只在它适合的场景里才成立。但至少在这一类页面上，轻量带来的收益是用户完全可以感知的，从数据里能清楚看到，体积和请求数量带来的差距远大于运行时的计算能力差距。

4.3 开发效率的真实感受

开发效率上，如果只看绝对速度，colibri 肯定不如直接用框架顺手，遇到需要现成组件库的场景，你还是得自己写。但 colibri 的定位就是避开那些场景。在它适合的场景里，比如落地页和活动页，一个页面的总代码量大概是用框架写法的两三成，因为不需要引入各种抽象的层，状态管理、路由、渲染全部可以在一个文件里串起来。

我个人的体感是，一个普通活动页从设计稿到上线，colibri 通常比用框架快 30% 左右。原因是内容页的复杂度本来就低，抽象的层越少，写起来越直接，排查问题的路径也越短。这里的差距不完全来自运行时，更多来自开发时的心智负担变轻。当然，这个数字只代表我自己的项目形态，不代表通用结论，但它确实反映了轻量方案在对应场景里的真实价值。

5. 接入真实项目之后踩到的一堆坑

每个项目都有文档之外的心酸。colibri 在真实项目里跑了几个月后，我陆续修掉了一批问题。这些坑单独看都不大，但每一个都会在特定场景下跳出来咬你一口。挑几个值得展开的，给想尝试类似思路的朋友避避坑，免得在同样的地方再摔一跤。

5.1 事件委托的坑：closest 的调用比想象中贵

事件委托在 document 上监听，派发时我用e.target.closest('[data-colibri-event]')找到真正要处理事件的元素。逻辑看起来没问题，但在滚动频繁的列表里，每次 touchmove 或 mousemove 都会触发一次closest，这个选择器匹配在低端安卓机上会造成肉眼可见的掉帧。一开始我完全没把closest当性能瓶颈，直到真机测试才发现问题。

优化方式有两个：一是对高频事件做节流，把派发频率压到合理的区间，比如滚动事件 16ms 内最多派发一次；二是把closest的查询结果缓存到 WeakMap 里。因为同一帧内，同一个 target 的匹配结果不会变化，缓存命中率非常高。这样优化之后，滚动掉帧问题基本消失。这个坑给我的教训是：选择器匹配在文档深层的复杂页面里并不廉价，尤其在低端设备上，任何看起来微小的操作都被放大了许多倍。

5.2 模板输出值的格式化

模板插值的另一个坑是：变量为 undefined 时输出空字符串，但 null 时会输出字符串 "null"，直接显示在用户页面上非常难看。比如后端某个字段本该返回对象，结果返回了 null，模板里直接渲染出一行 "null"，用户看到的第一反应就是这个页面坏了。

后来在编译输出前加了一个统一的格式化逻辑：null 和 undefined 输出空字符串，对象输出 JSON 字符串，数字和布尔值按原始值输出。改动只有几行，但对后端不稳定的字段结构容忍度提升很明显。接口少返回一个字段，页面上不会再出现奇怪的字符。这种问题在真实项目里几乎一定会遇到，越早设计进模板引擎越好。

5.3 动态插入内容的事件绑定

因为 colibri 用模板字符串生成 HTML，有些动态插入的节点带有>