Cloudflare Worker 实验性

Elysia 现在通过一个实验性的 Cloudflare Worker 适配器支持 Cloudflare Worker。

1. 您需要 Wrangler 来设置并启动开发服务器。

wrangler init elysia-on-cloudflare

2. 然后将 Cloudflare Adapter 添加到您的 Elysia 应用中，并在导出应用之前确保调用 .compile()。

import { Elysia } from 'elysia'
import { CloudflareAdapter } from 'elysia/adapter/cloudflare-worker'

export default new Elysia({
	adapter: CloudflareAdapter 
})
	.get('/', () => 'Hello Cloudflare Worker!')
	// 这是在 Cloudflare Worker 上使 Elysia 工作的必需步骤
	.compile() 

3. 确保在您的 wrangler 配置中将 compatibility_date 设置为至少 2025-06-01。

wrangler.jsonc

{
	"$schema": "node_modules/wrangler/config-schema.json",
 	"name": "elysia-on-cloudflare",
	"main": "src/index.ts",
	"compatibility_date": "2025-06-01"
}

wrangler.toml

main = "src/index.ts"
name = "elysia-on-cloudflare"
compatibility_date = "2025-06-01"

4. 现在您可以使用以下命令启动开发服务器：

wrangler dev

这应该会在 http://localhost:8787 启动开发服务器。

Elysia 不需要 nodejs_compat 标志，因为 Elysia 不使用任何 Node.js 内置模块（或者我们使用的那些模块尚未支持 Cloudflare Worker）。

限制

以下是在 Cloudflare Worker 上使用 Elysia 的已知限制：

1. Elysia.file 和 Static Plugin 无法工作 由于缺少 fs 模块
2. OpenAPI Type Gen 无法工作 由于缺少 fs 模块
3. 您无法在服务器启动之前定义 Response，或使用这样做插件
4. 您无法内联值

import { Elysia } from 'elysia'

new Elysia()
	// 这将抛出错误
    .get('/', 'Hello Elysia')
    .listen(3000)

静态文件

Static Plugin 无法工作，但您仍然可以使用 Cloudflare 的内置静态文件服务 来提供静态文件。

将以下内容添加到您的 wrangler 配置中：

wrangler.jsonc

{
	"$schema": "node_modules/wrangler/config-schema.json",
 	"name": "elysia-on-cloudflare",
	"main": "src/index.ts",
	"compatibility_date": "2025-06-01",
	"assets": { "directory": "public" } 
}

wrangler.toml

name = "elysia-on-cloudflare"
main = "src/index.ts"
compatibility_date = "2025-06-01"
assets = { directory = "public" } 

创建一个 public 文件夹并将您的静态文件放入其中。

例如，如果您的文件夹结构如下：

│
├─ public
│  ├─ kyuukurarin.mp4
│  └─ static
│     └─ mika.webp
├─ src
│  └── index.ts
└─ wrangler.toml

然后您应该能够从以下路径访问您的静态文件：

• http://localhost:8787/kyuukurarin.mp4
• http://localhost:8787/static/mika.webp

绑定

您可以通过从 cloudflare:workers 导入 env 来使用 Cloudflare Workers 绑定。

import { Elysia } from 'elysia'
import { CloudflareAdapter } from 'elysia/adapter/cloudflare-worker'
import { env } from 'cloudflare:workers'

export default new Elysia({
	adapter: CloudflareAdapter
})
	.get('/', () => `Hello ${await env.KV.get('my-key')}`) 
	.compile()

有关绑定的更多信息，请参阅 Cloudflare Workers: Binding。

AoT 编译

以前，要在 Cloudflare Worker 上使用 Elysia，您必须将 aot: false 传递给 Elysia 构造函数。

现在这不再必要，因为 Cloudflare 现在支持在启动期间进行函数编译。

从 Elysia 1.4.7 开始，您现在可以使用 Cloudflare Worker 进行提前编译，并删除 aot: false 标志。

import { Elysia } from 'elysia'
import { CloudflareAdapter } from 'elysia/adapter/cloudflare-worker'

export default new Elysia({
	aot: false, 
	adapter: CloudflareAdapter 
})

否则，如果您不想使用提前编译，您仍然可以使用 aot: false，但我们推荐您使用它以获得更好的性能和准确的插件封装。