← Dynamic Workers / dynamic-workers

Начало работы

Вы можете создать Worker, который во время выполнения запускает другие Workers, называемые Dynamic Workers, чтобы выполнять код по требованию в безопасной изолированной среде. Вы предоставляете код, выбираете, какие привязки будут доступны Dynamic Worker, и определяете, будет ли у Dynamic Worker доступ к сети.

Dynamic Workers поддерживают два режима загрузки:

load(code) создает новый Dynamic Worker для одноразового выполнения.
get(id, callback) кеширует Dynamic Worker по ID, чтобы он оставался прогретым между запросами.

load() лучше всего подходит для разового выполнения кода, например при использовании Code Mode. get(id, callback) лучше подходит, когда один и тот же код будет обрабатывать последующие запросы, например при разработке приложений.

Попробовать

Dynamic Workers Starter

Используйте этот пример «hello world» стартовый шаблон ↗ чтобы развернуть Worker, способный загружать и выполнять Dynamic Worker.

Dynamic Workers Playground

Вы также можете развернуть Dynamic Workers Playground ↗, где можно писать или импортировать код, собирать его в бандл во время выполнения с помощью @cloudflare/worker-bundler, выполнить его через Dynamic Worker и увидеть ответы и логи выполнения в реальном времени.

Настройка Worker Loader

Чтобы Worker мог создавать Dynamic Workers, ему нужна привязка Worker Loader. В отличие от большинства привязок Workers, эта привязка не указывает на какой-либо конкретный внешний ресурс, а просто предоставляет доступ к API Worker Loader.

Настройте это следующим образом в конфигурации вашего Worker wrangler.jsonc:

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

[[worker_loaders]]
binding = "LOADER"

После этого ваш Worker получит доступ к Worker Loader API через env.LOADER.

Запуск Dynamic Worker

Используйте env.LOADER.load() для создания Dynamic Worker и его запуска:

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

			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() создает Dynamic Worker из кода, определенного в modules и возвращает stub, который его представляет.

worker.getEntrypoint().fetch(request) передаёт входящий запрос у Dynamic Worker в fetch() обработчик, который обрабатывает его и возвращает ответ.

Повторное использование Dynamic Worker между запросами

Если вы предполагаете загружать один и тот же Worker несколько раз, используйте get(id, callback) вместо load(). id должен быть уникальной строкой, идентифицирующей конкретный код, который вы собираетесь загрузить. Когда runtime видит одинаковый id снова, он может использовать существующий Worker вместо создания нового, если тот еще не был вытеснен.

Предоставленный вами колбэк вызывается только в том случае, если 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-28",
		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-модули и CommonJS), Python и WebAssembly (Wasm). Передавайте код JavaScript и Python в виде строк в modules объект. Передавайте скомпилированные бинарные файлы Wasm как { wasm: ArrayBuffer } объекты модулей.

Здесь нет этапа сборки, поэтому такие языки, как TypeScript, необходимо скомпилировать в JavaScript перед передачей в load() или get().

Полный список поддерживаемых типов модулей см. в Справочник по API.

Python Workers

Чтобы запустить код Python в Dynamic Worker, необходимо включить python_workers флаг совместимости. Без этого флага Dynamic Worker не сможет загрузить среду выполнения Python.

const worker = env.LOADER.load({
	compatibilityDate: "2026-08-28",
	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() accept:

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-28" };
});

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 и сборку. Она возвращает mainModule и modules готов к передаче напрямую в load() или get().