Elysia 中文文档

简体中文

English

简体中文

English

主题

配置 ​

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
})

AOT ​

自 0.4.0 起 ​

提前编译（Ahead of Time compilation）。

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

ts
import { 
Elysia
 } from 'elysia'

new 
Elysia
({
	
aot
: true
})

详细信息 ​

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

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

ts
import { 
Elysia
 } from 'elysia'

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

禁用提前编译

选项 - @default false ​

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

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

名称 ​

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

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 起 ​

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

ts
import { 
Elysia
, 
t
 } from 'elysia'

new 
Elysia
({
	
normalize
: true
})

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

选项 - @default true

  • true: Elysia 将字段强制转换为指定的模式。

  • 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

种子 ​

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

ts
import { 
Elysia
 } from 'elysia'

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

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

严格路径 ​

Elysia 是否应该严格处理路径。

根据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')
		}
	}
})

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

查看serve.tls以获取可用配置。

serve.hostname ​

@default 0.0.0.0

服务器应监听的主机名。

serve.id ​

使用 ID 唯一标识服务器实例。

此字符串将用于热重载服务器，而不会中断待处理的请求或网页套接字。如果未提供，将生成一个值。要禁用热重载，请将此值设置为 null。

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 解密，

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 方案的标签，类似于详细信息。

ts
import { 
Elysia
 } from 'elysia'

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

WebSocket ​

覆盖 WebSocket 配置。

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

该配置扩展了Bun 的 WebSocket API。

示例 ​

ts
import { Elysia } from 'elysia'

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

试验性 ​

试用可能在未来版本的 Elysia 中可用的实验性功能。

experimental.encodeSchema ​

处理自定义 t.Transform 方案，并在将响应返回给客户端之前自定义 Encode。

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

ts
import { 
Elysia
, 
t
 } from 'elysia'

new 
Elysia
({ 
experimental
: { 
encodeSchema
: true } })

选项 - @default false ​

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

贡献者

The avatar of contributor named as 一纸忘忧 一纸忘忧

页面历史