Cloudflare Worker 实验性

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

1. 你需要使用 Wrangler 进行设置，并启动开发服务器。

wrangler init elysia-on-cloudflare

2. 接着将 Cloudflare 适配器添加到你的 Elysia 应用，并确保在导出应用前调用 .compile()。

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

export default new Elysia({
	adapter: CloudflareAdapter 
})
	.get('/', () => 'Hello Cloudflare Worker!')
	// 使 Elysia 能在 Cloudflare Worker 上运行所必需
	.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

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

pnpm

如果你使用 pnpm，pnpm 默认不会自动安装 peer 依赖，需要你手动安装额外依赖。

pnpm add @sinclair/typebox openapi-types

限制

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

1. Elysia.file 和 静态插件 不可用，因为缺少 fs 模块支持，详见静态文件部分的替代方案
2. OpenAPI 类型生成 不可用，因为缺少 fs 模块支持
3. 你不能在服务器启动前定义Response，也不能使用会这样做的插件
4. 由于第 3 点，你不能内联一个值。

import { Elysia } from 'elysia'

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

静态文件

静态插件 不可用，但你仍然可以使用 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 时，你需要给 Elysia 构造函数传入 aot: false。

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

从 Elysia 1.4.7 版本起，你可以在 Cloudflare Worker 上启用预编译（Ahead of Time Compilation），并且可以去掉 aot: false 选项。

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

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

当然，如果你不想使用预编译，仍然可以使用 aot: false，但我们推荐启用以获得更好的性能和更准确的插件封装。