Elysia
为 Bun 深度优化、强调端到端类型安全与优秀开发体验的 TypeScript 后端框架。
项目概述
Elysia 将高性能 HTTP 服务、运行时 Schema 验证、生命周期 Hook、插件系统和 Eden 类型客户端组合在一套链式 API 中。它以 Bun 为首选运行时，也可通过适配器运行在 Node.js 等环境。
Elysia 是一个以人体工程学和类型完整性为核心的 TypeScript 后端框架。它会从路由中声明的请求与响应 Schema 同时生成运行时验证、TypeScript 类型和 OpenAPI 信息，减少手写接口类型的重复。框架通过清晰的请求生命周期、可组合 Elysia 实例和作用域明确的插件组织复杂服务，并使用 Eden Treaty 在客户端共享服务端类型。Elysia 对 Bun 的 HTTP 与运行时能力做了深度优化，同时提供 Node.js 和 Web Standard 等适配路径。
主要特点
Elysia 将运行时验证、静态类型、路由生命周期和客户端契约放在同一条类型链中。
端到端类型安全
从路由、参数、请求体到响应状态持续推断类型，并可通过 Eden Treaty 将契约直接提供给客户端。
Schema 即单一事实来源
内置 t Schema 基于 TypeBox，可同时完成运行时验证、静态推断和 OpenAPI Schema 生成。
支持 Standard Schema
除内置 Schema 外，也能直接使用 Zod、Valibot、ArkType、Effect Schema 等验证库。
细粒度请求生命周期
从 Request、Parse、Transform、Validation 到 Before Handle、After Handle、Error 和 Trace 均可插入 Hook。
可组合插件实例
每个 Elysia 实例既能独立运行也能作为插件复用，并通过 local、scoped、global 控制生命周期传播范围。
为 Bun 深度优化
充分利用 Bun 的服务端、测试、打包和运行时能力，面向低延迟与快速开发反馈进行优化。
多运行时适配
除 Bun 外，可通过 @elysia/node 等适配器运行在 Node.js，并提供 Cloudflare、Vercel、Deno 等集成路径。
完整的服务端生态
官方提供 OpenAPI、JWT、CORS、Cookie、WebSocket、OpenTelemetry、静态文件和定时任务等插件。
适用场景
适合采用 Bun、重视接口类型完整性，或希望用少量样板代码构建高性能 TypeScript 服务的项目。
Bun 原生 API 服务
适合希望统一运行时、包管理、测试与开发服务器，并充分利用 Bun 性能的新项目。
类型安全的全栈应用
Eden Treaty 可让前端从服务端路由推断参数、请求体、响应数据与错误类型，减少契约漂移。
高性能微服务
较低框架开销、预编译 Schema 和模块化插件适合职责清晰的内部服务与边缘接口。
Schema 驱动 API
适合需要严格验证 JSON、查询、参数、Cookie 和响应，并自动生成 OpenAPI 文档的团队。
实时与流式服务
可结合 WebSocket、SSE、流式响应和 Bun 网络能力构建通知、协作和实时数据应用。
模块化业务后端
具名插件、Guard、Macro 和生命周期作用域适合拆分认证、数据库、领域模块及跨切面逻辑。
优点与注意事项
技术选型不仅要看能力，也要理解它带来的团队成本。
主要优点
Elysia 擅长的地方
- Schema 同时服务运行时验证、类型推断与 API 文档
- 链式 API 能持续保留路由上下文和精确的 TypeScript 类型
- Eden Treaty 提供无需代码生成的端到端类型客户端
- 为 Bun 深度优化，开发、测试和运行体验集成度高
- 生命周期阶段清晰，便于实现认证、转换、错误处理与观测
- 插件实例可组合，并能显式控制依赖和 Hook 传播范围
需要注意
采用前应考虑的问题
框架虽然支持多个运行时，但性能特征、插件兼容性和开发体验以 Bun 最完整；选择其他运行时应先做验证。
在 Node.js 中需要安装并配置 @elysia/node，Bun 专属文件、SQLite 或网络 API 也不能直接跨运行时复用。
不恰当地拆开路由、丢失实例返回类型或使用过宽的显式类型，可能让 Eden 和路由上下文失去精确推断。
Hook 默认具有封装边界，不会自动影响所有父级路由；local、scoped 和 global 选错可能造成鉴权或日志遗漏。
验证规则过宽会削弱安全性，过度复杂则增加编译与响应成本；请求和响应 Schema 都应纳入测试。
复杂企业集成、长期运维案例和第三方插件数量不及 Express、Fastify 或 NestJS，关键依赖应提前验证。
快速开始
使用 Bun 创建一个带请求 Schema、响应状态、无端口测试和 Eden Treaty 客户端的任务 API。
bashbun create elysia elysia-tasks
cd elysia-tasks
bun installtypescriptimport { Elysia, t } from "elysia";
export const app = new Elysia({ prefix: "/api" })
.get("/health", () => ({ status: "ok" }))
.post(
"/tasks",
({ body, status }) =>
status(201, {
id: crypto.randomUUID(),
title: body.title,
completed: false,
}),
{
body: t.Object({
title: t.String({ minLength: 1, maxLength: 120 }),
}),
},
);
export type App = typeof app;typescriptimport { app } from "./app";
app.listen(3000);
console.log(
`Elysia is running at http://localhost:${app.server?.port}`,
);typescriptimport { describe, expect, it } from "bun:test";
import { app } from "../src/app";
describe("tasks API", () => {
it("creates a task", async () => {
const response = await app.handle(
new Request("http://localhost/api/tasks", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ title: "学习 Elysia" }),
}),
);
expect(response.status).toBe(201);
expect(await response.json()).toMatchObject({
title: "学习 Elysia",
completed: false,
});
});
});typescriptimport { treaty } from "@elysiajs/eden";
import type { App } from "../server/src/app";
const api = treaty<App>("http://localhost:3000");
const { data, error } = await api.api.tasks.post({
title: "完成 Elysia 快速开始",
});
if (error) {
throw new Error(`创建任务失败：${error.status}`);
}
console.log(data.id, data.title);下一步：先保持路由链和 Schema 可推断，再按业务边界拆分具名插件；跨运行时部署前应验证所用插件、文件 API 和网络能力是否得到目标适配器支持。
类似项目
这些现代服务端框架也重视性能、类型安全或多运行时开发体验。
Elysia vs Hono
Elysia 和 Hono 都提供现代 TypeScript API 与端到端类型能力。Elysia 以 Bun、Schema 驱动和丰富生命周期为中心；Hono 则以 Web 标准、小体积和广泛运行时适配为主要优势。
| 比较维度 | Elysia | Hono |
|---|---|---|
| 核心定位 | Bun 优先、Schema 驱动的类型安全后端框架 | Web 标准优先的轻量多运行时框架 |
| 首选运行时 | Bun，其他运行时通过适配器支持 | Workers、Deno、Bun、Node 等多运行时并重 |
| 请求上下文 | Context 解构 body、params、query、set、status 等 | Context 提供 req、env、json、text、header 等 API |
| 验证方式 | 内置 t Schema，并支持 Standard Schema | Validator 中间件，可配合 Zod 等 Schema 库 |
| 类型客户端 | Eden Treaty，从服务端实例推断完整契约 | hc RPC，从 AppType 推断请求与响应 |
| 扩展模型 | Elysia 插件、生命周期 Hook、Guard 和 Macro | 洋葱中间件、Helper、路由组合与平台适配器 |
| 更适合 | Bun 服务、严格 Schema 和深度类型推断 | 边缘 API、跨运行时和广泛平台部署 |
如果团队已采用 Bun，希望 Schema、验证、OpenAPI 和客户端类型形成紧密的一体化体验，Elysia 很有吸引力；如果首要目标是跨 Workers、Deno、Bun 与 Node 复用代码，或需要更广泛的中间件和平台适配，Hono 通常更稳妥。最终应以目标运行时、插件兼容性、类型检查速度和真实负载测试选择。
资料核验
版本、维护信息与本页采用的官方资料来源。
本次核验覆盖 Elysia 的核心定位、主要能力、官方入口与开源许可。项目版本持续更新，具体补丁版本、兼容性和迁移要求请在采用前继续核对官方发布记录。
官方仓库未归档，核验时最近可见的代码活动日期为 2026 年 7 月 25 日。该状态表示项目近期仍有公开维护活动，不代表固定发布频率或长期支持承诺。