开始使用 · Cloudflare Dynamic Workers docs

您可以创建一个能够在运行时启动其他 Workers（称为 Dynamic Workers）的 Worker，以便在安全的沙箱环境中按需执行代码。您只需提供代码，选择 Dynamic Worker 可以访问哪些绑定，并控制 Dynamic Worker 是否可以访问网络。

Dynamic Workers 支持两种加载模式：

load(code) 创建一个全新的 Dynamic Worker 用于一次性执行。
get(id, callback) 按 ID 缓存 Dynamic Worker，以便在各个请求之间保持预热状态。

load() 最适合一次性代码执行，例如使用 Code Mode 时。如果在构建应用程序时相同的代码将接收后续请求，则 get(id, callback) 会更好。

试用

Dynamic Workers Starter

使用这个“hello world” starter ↗ 部署一个可以加载和执行 Dynamic Workers 的 Worker。

Dynamic Workers Playground

您也可以部署 Dynamic Workers Playground ↗，在这里您可以编写或导入代码，在运行时使用 @cloudflare/worker-bundler 打包，通过 Dynamic Worker 执行它，并查看实时响应和执行日志。

配置 Worker Loader

为了让 Worker 能够创建 Dynamic Workers，它需要一个 Worker Loader 绑定。与大多数 Workers 绑定不同，该绑定不指向任何特定的外部资源；它仅提供对 Worker Loader API 的访问。

在您的 Worker 的 wrangler.jsonc 中进行如下配置：

{
	"worker_loaders": [
		{
			"binding": "LOADER",
		},
	],
}

[[worker_loaders]]
binding = "LOADER"

之后，您的 Worker 即可通过 env.LOADER 访问 Worker Loader API。

运行 Dynamic Worker

使用 env.LOADER.load() 创建一个 Dynamic Worker 并运行它：

export default {
	async fetch(request, env) {
		// Load a worker.
		const worker = env.LOADER.load({
			compatibilityDate: "2026-08-17",

			mainModule: "src/index.js",
			modules: {
				"src/index.js": `
					export default {
						fetch(request) {
							return new Response("Hello from a dynamic Worker");
						},
					};
				`,
			},

			// Block all outbound network access from the Dynamic Worker.
			globalOutbound: null,
		});

		// Get the Dynamic Worker's `export default` entrypoint.
		// (A Worker can also export separate, named entrypoints.)
		let entrypoint = worker.getEntrypoint();

		// Forward the HTTP request to it.
		return entrypoint.fetch(request);
	},
};

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		// Load a worker.
		const worker = env.LOADER.load({
			compatibilityDate: "$today",

			mainModule: "src/index.js",
			modules: {
				"src/index.js": `
					export default {
						fetch(request) {
							return new Response("Hello from a dynamic Worker");
						},
					};
				`,
			},

			// Block all outbound network access from the Dynamic Worker.
			globalOutbound: null,
		});

		// Get the Dynamic Worker's `export default` entrypoint.
		// (A Worker can also export separate, named entrypoints.)
		let entrypoint = worker.getEntrypoint();

		// Forward the HTTP request to it.
		return entrypoint.fetch(request);
	},
};

在这个例子中，env.LOADER.load() 从 modules 定义的代码创建一个 Dynamic Worker，并返回代表它的一个 stub。

worker.getEntrypoint().fetch(request) 将传入的请求发送给 Dynamic Worker 的 fetch() 处理程序，处理后返回一个响应。

在多个请求间重用 Dynamic Worker

如果您希望多次加载完全相同的 Worker，请使用 get(id, callback) 而不是 load()。id 应该是一个唯一字符串，用于标识您打算加载的特定代码。当运行时再次看到相同的 id，它可以重用现有的 Worker 而不是创建新的，前提是它还没有被驱逐。

您提供的 callback 只有在 Worker 尚未加载时才会被调用。这让您可以在 Worker 已经在运行时跳过从存储中加载代码的步骤。

const worker = env.LOADER.get("hello-v1", async () => {
	// Callback only runs if there is not already a warm
	// instance available.

	// Load code from storage.
	let code = await env.MY_CODE_STORAGE.get("hello-v1");

	// Return the same format as `env.LOADER.load()` accepts.
	return {
		compatibilityDate: "2026-08-17",
		mainModule: "index.js",
		modules: { "index.js": code },
		globalOutbound: null,
	};
});

const worker = env.LOADER.get("hello-v1", async () => {
	// Callback only runs if there is not already a warm
	// instance available.

	// Load code from storage.
	let code = await env.MY_CODE_STORAGE.get("hello-v1");

	// Return the same format as `env.LOADER.load()` accepts.
	return {
		compatibilityDate: "$today",
		mainModule: "index.js",
		modules: { "index.js": code, },
		globalOutbound: null,
	};
});

支持的语言

Dynamic Workers 支持 JavaScript（ES modules 和 CommonJS）以及 Python。代码在 modules 对象中作为字符串传递。没有构建步骤，因此在传给 load() 或 get() 之前，必须将诸如 TypeScript 之类的语言编译为 JavaScript。

有关支持的模块类型的完整列表，请参阅 API 参考。

Python Workers

要在 Dynamic Worker 中运行 Python 代码，必须包含 python_workers 兼容性标志。如果没有这个标志，Dynamic Worker 将无法加载 Python 运行时。

const worker = env.LOADER.load({
	compatibilityDate: "2026-08-17",
	compatibilityFlags: ["python_workers"],
	mainModule: "worker.py",
	modules: {
		"worker.py": `
from workers import Response, WorkerEntrypoint

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return Response("Hello from Python!")
    `,
	},
});

const worker = env.LOADER.load({
  compatibilityDate: "$today",
  compatibilityFlags: ["python_workers"],
  mainModule: "worker.py",
  modules: {
    "worker.py": `
from workers import Response, WorkerEntrypoint

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return Response("Hello from Python!")
    `,
  },
});

使用 TypeScript 和 npm 依赖

如果您的 Dynamic Worker 需要 TypeScript 编译或 npm 依赖项，必须在传递给 Worker Loader 之前转译并打包代码。

@cloudflare/worker-bundler ↗ 是一个自动处理此过程的库。使用它将源文件打包成 load() 和 get() 接受的格式：

import { createWorker } from "@cloudflare/worker-bundler";

const worker = env.LOADER.get("my-worker", async () => {
	const { mainModule, modules } = await createWorker({
		files: {
			"src/index.ts": `
				import { Hono } from 'hono';
				const app = new Hono();
				app.get('/', (c) => c.text('Hello from Hono!'));
				export default app;
			`,
			"package.json": JSON.stringify({
				dependencies: { hono: "^4.0.0" },
			}),
		},
	});

	return { mainModule, modules, compatibilityDate: "2026-08-17" };
});

import { createWorker } from "@cloudflare/worker-bundler";

const worker = env.LOADER.get("my-worker", async () => {
	const { mainModule, modules } = await createWorker({
		files: {
			"src/index.ts": `
				import { Hono } from 'hono';
				const app = new Hono();
				app.get('/', (c) => c.text('Hello from Hono!'));
				export default app;
			`,
			"package.json": JSON.stringify({
				dependencies: { hono: "^4.0.0" },
			}),
		},
	});

	return { mainModule, modules, compatibilityDate: "$today" };
});

createWorker() 负责 TypeScript 编译、从 npm 解析依赖项以及打包。它返回准备好直接传递给 load() 或 get() 的 mainModule 和 modules。