Elysia：跑在 Bun 上的人体工学 TypeScript 后端框架

Elysia 是一个主打”人体工学（Ergonomic）“的后端 TypeScript 框架，官方定位是”为人类设计的框架（Ergonomic Framework for Humans）“。它最初随 Bun 运行时一同走红，靠一条”245 万请求每秒”的基准数据进入开发者视野；但真正让它区别于 Express、Fastify 的，不是快，而是它把”Schema 即唯一真相源”贯穿到请求校验、类型推断、OpenAPI 文档和前后端通信的整条链路上。本文基于 Elysia 官网与官方公布的 TechEmpower 基准，分析它的设计哲学、性能口径与真实适用边界。

一、背景：TypeScript 后端的”类型税”

Node.js 生态长期存在一个矛盾：用 TypeScript 写后端，类型在编译期就被擦除，运行时并没有任何东西保证前端发来的 body 真的是你期望的形状。于是社区演化出一整套补丁：运行时用 Zod 等库再校验一遍、手动维护 OpenAPI 文档、用 tRPC 之类方案在前后端之间来回同步类型、写代码生成脚本把后端类型导给前端。每一环都在，每一环都可能漂移——文档和实现对不上、校验通过了但类型没推出来、前端拿到的字段名拼错要到运行时才炸。

Elysia 的回答是：与其在事后补类型，不如让一份 Schema 同时承担”运行时校验 + 类型推导 + 文档 + 客户端类型”四个职责。

二、是什么：以 Schema 为中心的后端框架

Elysia 是一个后端 Web 框架，用 TypeScript 编写，默认运行在 Bun 上，但官网同时列出 Deno、Node.js 与 Cloudflare Vercel/Netlify 等部署目标。它的核心 API 刻意保持得像”原生 JavaScript”：

new Elysia()
	.get('/', 'Hello World')
	.get('/stream', function* () { yield 'Hello'; yield 'World' })
	.ws('/realtime', { message(ws, msg) { ws.send('got:' + msg) } })
	.listen(3000)

路由处理函数直接返回字符串、数字、JSON、文件或用 yield 生成的流；WebSocket 基于内置的 µWebSocket，三行代码就能起实时通道。官方反复强调”Just return”——框架不强制你包裹响应对象。

三、技术机制：Single Source of Truth

Elysia 的设计主轴是官网所说的 Single Source of Truth：Schema 是整个服务端唯一的真相来源。

• 请求校验与类型推导合一：用 t.Object({...}) 定义 body，框架在运行时校验并规范化输入，同时在类型层面把推导结果喂给 handler——既不会让非法数据进入业务逻辑，也不需要你手写接口类型。
• Standard Schema 兼容，不绑死校验器：这是 Elysia 区别于许多”自家 schema 全家桶”框架的一点。它内置 TypeBox，但官方明确支持把 Zod、Valibot、ArkType、Effect 等主流 Standard Schema 实现”接进来”，且类型推导与 OpenAPI 生成都能继续工作。对已经在用 Zod 的团队，这避免了换框架=换校验栈的迁移成本。
• 端到端类型安全（Eden Treaty）：通过 @elysia/eden 的 treaty<App>()，前端直接引用后端应用类型，像调本地函数一样调 API，无需代码生成；官方还支持对多 HTTP 状态码做可辨识联合（discriminated union），让你穷尽式地处理所有错误分支。
• OpenAPI 一行生成 + TypeScript-to-OpenAPI：挂一个 openapi() 插件即得到 Swagger UI 式文档；更新的 fromTypes() 甚至能直接从 Prisma、Drizzle 等任意 TypeScript 库的类型推导 OpenAPI，不需要注解、不需要跑 CLI。
• 可观测性：官方提供一等公民的 OpenTelemetry 集成，埋点内置。

四、关键数据：那个 245 万是怎么来的

官网首页最抓眼的是一组吞吐对比：

官网据此宣称”比 Express 快 21 倍、比 Fastify 快 6 倍”。

五、评测方法批判：PlainText 不是你的业务

必须把口径说清楚，否则容易被首页数字误导。官方在图注里自己写明：数据来自 TechEmpower Benchmark Round 22（2023-10-17）的 PlainText 场景。这意味着：

1. 它测的是”裸字符串响应”——请求进来、直接回一个 “Hello”，没有数据库查询、没有 JSON 序列化、没有业务计算。这个场景主要奖励运行时本身的 I/O 与调度效率，Bun（用 Zig 编写、内置高效网络层）在这里天然占优。
2. 时间偏旧：Round 22 是 2023 年 10 月的数据，此后 Bun、Node、Fastify 都有多个大版本，21×/6× 的倍数不能直接平移到今天的生产代码。
3. 跨语言对比要打折：拿 TypeScript 框架的 PlainText 成绩去和 Gin、Spring 比”业务性能”是不成立的——一旦接上数据库、ORM、序列化，语言与运行时的裸吞吐优势会被业务 IO 大幅摊薄。

换句话说，Elysia 官方数据证明的是”在 Bun 上它几乎没有框架层开销”，而不是”你的 REST API 会比别人快 21 倍”。这是官网自己标注的口径，值得在选型时照单全收。

六、优势与局限

优势：

1. 类型安全体验在 TS 后端里第一梯队：Schema 同时解决校验、类型、文档、客户端类型，端到端无需代码生成，对重视 DX 的团队吸引力强；
2. 不绑架校验器：拥抱 Standard Schema，Zod/Valibot/ArkType 用户可以平滑迁入；
3. 框架层开销极低：在 Bun 上连 PlainText 都能逼近运行时极限，路由/WebSocket/文件/流开箱即用；
4. 文档自动化：OpenAPI 与 Swagger UI 由 Schema 生成，杜绝文档与实现漂移。

局限：

1. 生态年轻：相比 Express/Fastify 十余年的中间件与教程生态，Elysia 的插件、排障资料、招人市场都还在早期，官网首页仍挂着”Elysia 2 beta”横幅，API 可能变动；
2. 深度绑定 Bun 叙事：最快成绩来自 Bun，若你的部署环境只能用 Node，性能故事要重算；
3. 基准外的真实性能未被官方覆盖：官方没有给出带 DB、带序列化的同场对比，复杂业务下的表现需要自己压测；
4. Schema 心智成本：一套贯穿全局的 Schema 抽象，对小项目可能是过度设计。

七、谁该关注

• 已经在用 Bun、想要比 Fastify 更少样板的 TS 团队：Elysia 几乎是 Bun 生态的默认框架，端到端类型安全能显著减少前后端联调摩擦；
• 被 tRPC/手写文档折腾过的全栈项目：Eden Treaty + 自动 OpenAPI 是它最有辨识度的卖点；
• 强依赖 Zod 校验栈的团队：Standard Schema 兼容意味着不必为框架放弃已有资产。

反之，如果你的团队必须长期锁定 Node LTS、需要海量现成 Express 中间件，或者只是写一个一次性小脚本，Elysia 的类型体系带来的复杂度未必划算——先把它当作一个”高性能 + 高 DX”的选项放进对比清单，用自己的真实路由压测一次再决定。

参考来源

• Elysia 官方网站
• TechEmpower Web Framework Benchmarks（Round 22）
• Koala 项目库条目：Elysia | Bun 生态的新锐框架