← Dynamic Workers / dynamic-workers

Začínáme

Můžete vytvořit Worker, který za běhu spouští další Workery, takzvané Dynamic Workers, aby na vyžádání spouštěl kód v zabezpečeném izolovaném prostředí. Sami dodáváte kód, vybíráte, ke kterým bindingům bude mít Dynamic Worker přístup, a určujete, zda se bude moci připojit k síti.

Dynamic Workers podporují dva režimy načítání:

load(code) vytvoří nový Dynamic Worker pro jednorázové spuštění.
get(id, callback) ukládá Dynamic Worker do cache podle ID, takže zůstává zahřátý mezi jednotlivými požadavky.

load() je nejlepší pro jednorázové spuštění kódu, například při použití Code Mode. get(id, callback) je lepší, když stejný kód bude přijímat další požadavky, například při vytváření aplikací.

Vyzkoušejte to

Dynamic Workers Starter

Použijte tento „hello world“ starter ↗ k nasazení Workeru, který dokáže načítat a spouštět Dynamic Workery.

Dynamic Workers Playground

Můžete také nasadit Dynamic Workers Playground ↗, kde můžete kód napsat nebo importovat, a za běhu jej zabalit pomocí @cloudflare/worker-bundler, spustit jej přes Dynamic Worker a sledovat odpovědi a logy spuštění v reálném čase.

Konfigurace Worker Loaderu

Aby mohl Worker vytvářet Dynamic Workers, potřebuje Worker Loader binding. Na rozdíl od většiny bindingů u Workers tento binding neukazuje na žádný konkrétní externí prostředek, pouze poskytuje přístup k Worker Loader API.

Nakonfigurujte to takto ve svém Workeru v wrangler.jsonc:

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

[[worker_loaders]]
binding = "LOADER"

Váš Worker pak bude mít přístup k Worker Loader API prostřednictvím env.LOADER.

Spuštění Dynamic Workeru

Použijte env.LOADER.load() k vytvoření Dynamic Workeru a jeho spuštění:

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

V tomto příkladu env.LOADER.load() vytvoří Dynamic Worker z kódu definovaného v modules a vrátí stub, který ho reprezentuje.

worker.getEntrypoint().fetch(request) odešle příchozí požadavek do Dynamic Workeru, konkrétně do jeho fetch() handler, který jej zpracuje a vrátí odpověď.

Opakované použití Dynamic Workeru napříč požadavky

Pokud očekáváte, že budete stejný Worker načítat vícekrát, použijte get(id, callback) místo load(). id by měl být jedinečný řetězec identifikující konkrétní kód, který chcete načíst. Když runtime uvidí stejný id znovu, může znovu použít existující Worker místo vytvoření nového, pokud ještě nebyl odstraněn z paměti.

Callback, který zadáte, se zavolá pouze tehdy, pokud Worker ještě není načtený. Díky tomu můžete přeskočit načítání kódu z úložiště, pokud Worker již běží.

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

Podporované jazyky

Dynamic Workers podporují moduly JavaScript (ES modules a CommonJS), Python a WebAssembly (Wasm). Kód JavaScriptu a Pythonu předávejte jako řetězce v modules objekt. Zkompilované binární soubory Wasm předejte jako { wasm: ArrayBuffer } objekty modulu.

Neexistuje žádný krok sestavení, takže jazyky jako TypeScript je nutné zkompilovat do JavaScriptu, než je předáte do load() nebo get().

Úplný seznam podporovaných typů modulů najdete v Referenční dokumentace API.

Python Workers

Chcete-li v Dynamic Workeru spustit kód Python, musíte zahrnout python_workers compatibility flag. Bez tohoto flagu se Dynamic Workeru nepodaří načíst Python runtime.

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!")
    `,
  },
});

Použití TypeScriptu a závislostí npm

Pokud váš Dynamic Worker vyžaduje kompilaci TypeScriptu nebo závislosti z npm, musí být kód před předáním Worker Loaderu transpilován a zabalen.

@cloudflare/worker-bundler ↗ je knihovna, která to za vás obstará. Použijte ji k zabalení zdrojových souborů do formátu, který load() a 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() se stará o kompilaci TypeScriptu, řešení závislostí z npm a bundlování. Vrací mainModule a modules připravené k přímému předání do load() nebo get().