elysiajs

Elysia v2

从这里开始

1. 检查 package.json、锁文件、运行时和应用结构。除非用户要求迁移，否则保留现有版本和惯例。
2. 此技能适用于 2.0.0-rc.0 或更高版本。对于 v1，请使用 迁移指南了解差异，而不是将其视为升级许可。如果不同的 beta 版本与之不符，请检查已安装的类型。
3. 只阅读任务所需的参考资料。版本列出了源代码修订版本、软件包基准版本和验证限制。
4. 检查类型并测试受影响的路由，包括其拒绝路径。参见测试。

基本规则

• 选项要放在处理函数之前。 .get(path, options, handler)、.get(path, handler) 和 .get(path, staticValue) 都有效。
• 保留返回的类型。 链接调用，或将结果绑定到新变量。重新赋值 let app = new Elysia() 不会扩大其推导类型。
• 路由之前注册钩子。 父级钩子要放在 .use(child) 之前，才能作用于子级路由。onRequest 在路由之前运行，不受注册顺序影响。参见生命周期。
• 声明有类型的依赖项。 每个独立定义的实例都应 .use() 其提供者。父级运行时继承不会让子级获得这些静态类型。参见组合。
• 为共享插件命名。 name 和 seed 会对钩子去重。每次调用仍会执行插件工厂。
• 返回预期的失败结果。 status() 和 problem() 会发送普通响应。返回的 Error 会进入错误钩子，并计入路由的返回类型。抛出的错误不会出现在该推导类型中。显式错误详情在生产环境中仍可能公开。参见错误处理。
• 根据架构推导类型。 使用 UnwrapSchema 或 UnwrapModels。TypeBox 1.x 没有架构 .static。将处理函数内联，并向服务传递普通值。
• 选择上下文生命周期。 decorate 和 state 是共享的。derive 会在每个请求的验证之后、beforeHandle 队列中运行。
• 默认情况下，守卫架构会覆盖。 路由会替换对应的继承架构。如果两者都要应用，请在守卫上使用 schema: 'merge'。
• 注册可选功能。 文件 MIME 验证需要检测器。WebSocket 需要 elysia/websocket。Node 需要 @elysia/node 和 Node 22.18 或更高版本。
• 务必查阅实际文档以获取最新功能、示例和参考资料。此技能是文档指南，而非文档的替代品。

Elysia 1 文档：https://elysiajs.com/llms.txt Elysia 2 文档：https://next.elysiajs.com/llms.txt

最小应用和测试

使用项目的测试运行器。此 Bun 示例不会打开端口。

// src/app.ts
import { Elysia, t } from 'elysia'

export const app = new Elysia()
	.get('/users/:id', {
		params: t.Object({ id: t.Number() })
	}, ({ params }) => ({ id: params.id }))

export type App = typeof app

// test/app.test.ts
import { expect, test } from 'bun:test'
import { app } from '../src/app'

test('coerces the id and rejects nonnumeric input', async () => {
	const response = await app.handle('/users/42')
	expect(response.status).toBe(200)
	expect(await response.json()).toEqual({ id: 42 })
	expect((await app.handle('/users/nope')).status).toBe(422)
})

运行 bun test 和项目的类型检查。对于新项目，请参见运行时设置。将 .listen() 保留在进程入口中。参见项目结构。

选择参考文档

任务	阅读
版本、同级依赖、源码与文档	版本
配置、路由、上下文、文件、流	核心 API
Hook、解析、派生上下文、释放	生命周期
插件、Hook 作用域、守卫、宏	组合
Schema、强制转换、上传、推导类型	验证
预期错误、异常映射、生产环境响应	错误
文件夹、服务、模型、依赖注入	项目结构
Cookie 值、验证、签名	Cookie
WebSocket 路由	WebSocket
路由测试、类型检查、延迟加载插件	测试
类型化客户端调用	Eden
OpenAPI Schema 和文档	OpenAPI
Bun、Node、Deno、Workers、前端框架集成	运行时
Bundle、AOT、二进制文件、Docker、部署	部署
Trace、Span、请求计时	可观测性
CORS、JWT、静态文件、cron、HTML、GraphQL	官方插件
数据库和外部库	Drizzle、Prisma、Better Auth、AI SDK、React Email
v1 语法和迁移	迁移
按模式查找示例	模式索引

新项目的默认设置

默认使用 Bun 和 t Schema。小型应用保留在一个文件中；按需按功能拆分。添加 Eden 以支持类型化客户端，并添加 OpenAPI 以编写 API 文档。