Elysia 中文文档

Appearance

在 AI 工具中打开 Anthropic

配置 ​

Elysia 提供了可配置的行为，允许我们自定义其功能的各个方面。

我们可以通过使用构造函数定义配置。

ts
import { Elysia, t } from 'elysia'

new Elysia({
	prefix: '/v1',
	normalize: true
})

适配器 ​

自 1.1.11 起 ​

用于在不同环境中使用 Elysia 的运行时适配器。

默认根据环境选择合适的适配器。

ts
import { Elysia, t } from 'elysia'
import { BunAdapter } from 'elysia/adapter/bun'

new Elysia({
	adapter: BunAdapter
})

allowUnsafeValidationDetails ​

自 1.4.13 起 ​

是否允许 Elysia 在生产环境的错误响应中包含不安全的验证详情。

ts
import { Elysia, t } from 'elysia'

new Elysia({
	allowUnsafeValidationDetails: true
})

默认情况下，Elysia 会在生产环境中省略所有验证详情。

这样做是为了防止泄露有关验证模式的敏感信息，例如字段名称和预期类型，这些信息可能会被攻击者利用。

理想情况下，这只应在公共 API 上启用，因为它可能泄露有关服务器实现的敏感信息。

选项 - @default false ​

  • true - 在生产环境的错误响应中包含不安全的验证详情
  • false - 在生产环境的错误响应中排除不安全的验证详情

AOT ​

自 0.4.0 起 ​

提前编译（Ahead of Time compilation）。

Elysia 内置了一个 JIT "编译器"，可以优化性能。

ts
import { Elysia } from 'elysia'

new Elysia({
	aot: true
})

禁用提前编译

选项 - @default false ​

  • true - 在启动服务器之前预编译每个路由

  • false - 完全禁用 JIT。启动时间更快，而不影响性能

详细信息 ​

为实例的所有路由定义 OpenAPI 方案。

此方案将用于生成实例所有路由的 OpenAPI 文档。

ts
import { Elysia } from 'elysia'

new Elysia({
	detail: {
		hide: true,
		tags: ['elysia']
	}
})

encodeSchema ​

在返回响应给客户端之前，使用自定义的 Encode 处理自定义的 t.Transform 模式。

这允许我们在向客户端发送响应之前为数据创建自定义编码函数。

ts
import { Elysia, t } from 'elysia'

new Elysia({ encodeSchema: true })

选项 - @default true ​

  • true - 在将响应发送给客户端之前运行 Encode
  • false - 完全跳过 Encode

name ​

定义实例的名称，用于调试和插件去重

ts
import { Elysia } from 'elysia'

new Elysia({
	name: 'service.thing'
})

nativeStaticResponse ​

自 1.1.11 起 ​

为每个运行时使用优化的函数来处理内联值。

ts
import { Elysia } from 'elysia'

new Elysia({
	nativeStaticResponse: true
})

示例 ​

如果在 Bun 上启用，Elysia 将内联值插入到 Bun.serve.static 中，从而提高静态值的性能。

ts
import { Elysia } from 'elysia'

// 这是
new Elysia({
	nativeStaticResponse: true
}).get('/version', 1)

// 相当于
Bun.serve({
	static: {
		'/version': new Response(1)
	}
})

规范化 ​

自 1.1.0 起 ​

是否应该将字段强制转换为指定的模式。

ts
import { Elysia, t } from 'elysia'

new Elysia({
	normalize: true
})

当在输入和输出中发现不在模式中规定的未知属性时，Elysia 应该如何处理字段？

选项 - @default true

  • true: Elysia 将使用 exact mirror 将字段强制转换为指定模式

  • typebox: Elysia 将使用 TypeBox's Value.Clean 将字段强制转换为指定模式

  • false: 如果请求或响应包含不在各自处理程序的模式中明确允许的字段，Elysia 将引发错误。

预编译 ​

自 1.0.0 起 ​

Elysia 是否应该在启动服务器之前预编译所有路由。

ts
import { Elysia } from 'elysia'

new Elysia({
	precompile: true
})

选项 - @default false

  • true: 在启动服务器之前对所有路由进行 JIT 编译

  • false: 动态按需编译路由

推荐将其保持为 false。

前缀 ​

定义实例所有路由的前缀

ts
import { Elysia, t } from 'elysia'

new Elysia({
	prefix: '/v1'
})

当定义前缀时，所有路由将以给定值为前缀。

示例 ​

ts
import { Elysia, t } from 'elysia'

new Elysia({ prefix: '/v1' }).get('/name', 'elysia') // 路径为 /v1/name

sanitize ​

一个函数或函数数组，在每次 t.String 验证时被调用和拦截。

允许我们读取并转换字符串为新的值。

ts
import { Elysia, t } from 'elysia'

new Elysia({
	sanitize: (value) => Bun.escapeHTML(value)
})

种子 ​

定义一个用于生成实例校验和的值，用于插件去重

ts
import { Elysia } from 'elysia'

new Elysia({
	seed: {
		value: 'service.thing'
	}
})

该值可以是任何类型，不限于字符串、数字或对象。

严格路径 ​

是否应严格处理路径。

根据RFC 3986，路径应与路由中定义的路径完全相等。

ts
import { Elysia, t } from 'elysia'

new Elysia({ strictPath: true })

选项 - @default false ​

  • true - 严格遵循RFC 3986 进行路径匹配
  • false - 容忍后缀 '/' 或反之亦然。

示例 ​

ts
import { Elysia, t } from 'elysia'

// 路径可以是 /name 或 /name/
new Elysia({ strictPath: false }).get('/name', 'elysia')

// 路径只能是 /name
new Elysia({ strictPath: true }).get('/name', 'elysia')

服务 ​

自定义 HTTP 服务器行为。

Bun 服务配置。

ts
import { Elysia } from 'elysia'

new Elysia({
	serve: {
		hostname: 'elysiajs.com',
		tls: {
			cert: Bun.file('cert.pem'),
			key: Bun.file('key.pem')
		}
	},
})

该配置扩展了Bun Serve API和Bun TLS

示例: 最大主体大小 ​

我们可以通过在 serve 配置中设置serve.maxRequestBodySize来设置最大主体大小。

ts
import { Elysia } from 'elysia'

new Elysia({
	serve: {
		maxRequestBodySize: 1024 * 1024 * 256 // 256MB
	}
})

默认情况下，最大请求体大小为 128MB (1024 * 1024 * 128)。 定义主体大小限制。

ts
import { Elysia } from 'elysia'

new Elysia({
	serve: {
		// 最大消息大小（以字节为单位）
	    maxPayloadLength: 64 * 1024,
	}
})

示例: HTTPS / TLS ​

通过传入密钥和证书的值，我们可以启用 TLS（SSL 的继任者）；两者均为启用 TLS 所必需。

ts
import { Elysia, file } from 'elysia'

new Elysia({
	serve: {
		tls: {
			cert: file('cert.pem'),
			key: file('key.pem')
		}
	}
})

示例：增加超时 ​

我们可以通过在 serve 配置中设置 serve.idleTimeout 来增加空闲超时。

ts
import { Elysia } from 'elysia'

new Elysia({
	serve: {
		// 将空闲超时增加到 60 秒
		idleTimeout: 60
	}
})

默认情况下，空闲超时为 30 秒。

serve ​

HTTP 服务器配置。

Elysia 扩展了 Bun 配置，开箱即用地支持 TLS，基于 BoringSSL。

有关可用配置，请参见 serve.tls。

serve.hostname ​

@default 0.0.0.0

服务器应监听的主机名。

serve.id ​

唯一标识服务器实例的 ID

该字符串将用于在不打断未完成请求或 WebSocket 的情况下热重载服务器。如果未提供，则会生成一个值。要禁用热重载，请将此值设置为 null。

serve.idleTimeout ​

@default 30（30 秒）

默认情况下，Elysia 将空闲超时设置为 30 秒，这意味着如果请求在 30 秒内未完成，它将被中止。

serve.maxRequestBodySize ​

@default 1024 * 1024 * 128（128MB）

请求体的最大大小（以字节为单位）

serve.port ​

@default 3000

监听的端口。

serve.rejectUnauthorized ​

@default NODE_TLS_REJECT_UNAUTHORIZED 环境变量

如果设置为 false，将接受任何证书。

serve.reusePort ​

@default true

是否应设置 SO_REUSEPORT 标志。

这允许多个进程绑定到同一端口，对负载均衡很有用。

该配置被覆盖，并默认由 Elysia 打开。

serve.unix ​

如果设置，HTTP 服务器将在 Unix 套接字上监听，而不是在端口上。

（不能与主机名+端口一起使用）

serve.tls ​

我们可以通过传入密钥和证书的值启用 TLS（SSL 的继任者）；这两者都是启用 TLS 所必需的。

ts
import { Elysia, file } from 'elysia'

new Elysia({
	serve: {
		tls: {
			cert: file('cert.pem'),
			key: file('key.pem')
		}
	}
})

Elysia 扩展了支持 TLS 的 Bun 配置，使用 BoringSSL 作为支持。

serve.tls.ca ​

可选覆盖受信任的 CA 证书。默认是信任 Mozilla 精心挑选的知名 CA。

当使用此选项明确指定 CA 时，Mozilla 的 CA 会完全被替换。

serve.tls.cert ​

PEM 格式的证书链。每个私钥应提供一条证书链。

每条证书链应包含为提供的私钥格式化的 PEM 证书，以及 PEM 格式的中间证书（如果有），按顺序排列，不包括根 CA（根 CA 必须提前为对等方所知，参见 ca）。

提供多个证书链时，顺序不必与其在密钥中的私钥顺序相同。

如果未提供中间证书，对等方将无法验证证书，握手将失败。

serve.tls.dhParamsFile ​

自定义 Diffie Helman 参数的 .pem 文件路径。

serve.tls.key ​

PEM 格式的私钥。PEM 允许加密私钥的选项。加密密钥将使用 options.passphrase 解密。

可以提供使用不同算法的多个密钥，可以是未加密的密钥字符串或缓冲区的数组，或者以对象形式的数组。

对象形式只能在数组中出现。

object.passphrase 为可选。加密密钥将使用提供的 object.passphrase（若已提供）或 options.passphrase（若未提供）进行解密。

serve.tls.lowMemoryMode ​

@default false

将 OPENSSL_RELEASE_BUFFERS 设置为 1。

这会降低整体性能，但节省一些内存。

serve.tls.passphrase ​

用于单个私钥和/或 PFX 的共享密码短语。

serve.tls.requestCert ​

@default false

如果设置为 true，服务器将请求客户端证书。

serve.tls.secureOptions ​

可选影响 OpenSSL 协议行为，这通常不是必需的。

应谨慎使用！

值是 OpenSSL 可选选项的 SSL_OP_* 的数字位掩码。

serve.tls.serverName ​

显式设置服务器名称。

标签 ​

为实例所有路由的 OpenAPI 方案定义标签，类似于 detail

ts
import { Elysia } from 'elysia'

new Elysia({
	tags: ['elysia']
})

systemRouter ​

在可能的情况下使用运行时/框架提供的路由器。

在 Bun 上，Elysia 将使用 Bun.serve.routes 并回退到 Elysia 自己的路由器。

websocket ​

覆盖 websocket 配置

建议将其保持为默认值，因为 Elysia 将自动生成适合处理 WebSocket 的配置

该配置扩展了 Bun's WebSocket API

示例 ​

ts
import { Elysia } from 'elysia'

new Elysia({
	websocket: {
		// 启用压缩和解压缩
    	perMessageDeflate: true
	}
})