INTEGRITY Dokumentace

← Cloudflare Workers / workers

Lokální vývoj

Kód Workeru můžete sestavit, spustit a otestovat na vlastním lokálním počítači ještě před nasazením do sítě Cloudflare. Umožňuje to Miniflare, simulátor, který spouští kód vašeho Workeru pomocí stejného runtime jako v produkci, workerd ↗.

Ve výchozím nastavení, vazby vašeho Workeru připojit se k lokálně simulovaným prostředkům, ale lze je nakonfigurovat tak, aby komunikovaly se skutečným produkčním prostředkem pomocí vzdálené bindings.

Základní koncepty

Provádění Workeru vs. Bindings

Při vývoji Workerů je důležité rozumět dvěma odlišným konceptům:

Spusťte lokální vývojový server

Lokální vývojový server můžete spustit pomocí:

  1. CLI Cloudflare Workers Wrangler, pomocí vestavěného wrangler dev příkazu.
npx wrangler dev
  1. Vite ↗, pomocí Cloudflare Vite plugin.
npx vite dev

Wrangler i Cloudflare Vite plugin používají Miniflare pod kapotou a jsou vyvíjeny a udržovány týmem Cloudflare. Pro pomoc s výběrem, kdy použít Wrangler a kdy Vite, se podívejte na náš návod Volba mezi Wrangler a Vite.

Výchozí hodnoty

Ve výchozím nastavení spuštění wrangler dev / vite dev (při použití Plugin Vite) znamená, že:

Bindings během místního vývoje

Bindings jsou rozhraní, která vašemu Workeru umožňují komunikovat s různými prostředky Cloudflare (například KV namespaces, R2 buckety, Databáze D1, Queues, Durable Objects, atd.). V kódu Workeru k nim přistupujete přes env objekt (například env.MY_KV).

Během místního vývoje váš kód Workeru komunikuje s těmito vazbami pomocí naprosto stejných volání API (například env.MY_KV.put()) stejně jako v nasazeném prostředí. Tyto lokální prostředky jsou zpočátku prázdné, ale můžete je naplnit daty podle postupu popsaného v Přidávání lokálních dat.

Remote Bindings

Remote Bindings jsou bindingy nakonfigurované tak, aby se během místního vývoje připojovaly k nasazenému vzdálenému prostředku místo toho lokálně simulovaného prostředku. Remote bindings podporuje Wrangler, Cloudflare Vite plugin, a @cloudflare/vitest-plugin balíček. Remote bindings můžete nakonfigurovat nastavením remote: true v definici bindingu.

Příklad konfigurace

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",

	"r2_buckets": [
		{
			"bucket_name": "screenshots-bucket",
			"binding": "screenshots_bucket",
			"remote": true,
		},
	],
}
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"

[[r2_buckets]]
bucket_name = "screenshots-bucket"
binding = "screenshots_bucket"
remote = true

Když jsou nakonfigurovány vzdálené bindingy, váš Worker stále spouští se lokálně, mění se pouze podkladové prostředky, ke kterým se vaše bindingy připojují. U všech bindingů označených remote: true, Miniflare bude směrovat své operace (například env.MY_KV.put()) k nasazenému prostředku. Všechny ostatní bindings, které nejsou výslovně nakonfigurované pomocí remote: true nadále používají výchozí lokální simulace.

Integrace s prostředími

Remote Bindings dobře fungují společně s Workers Environments. Chcete-li chránit produkční data, můžete vytvořit vývojové nebo staging prostředí a určit jiné zdroje ve svém Konfigurace Wrangleru než byste použili pro produkci.

Například:

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",

	"env": {
		"production": {
			"r2_buckets": [
				{
					"bucket_name": "screenshots-bucket",
					"binding": "screenshots_bucket",
				},
			],
		},
		"staging": {
			"r2_buckets": [
				{
					"bucket_name": "preview-screenshots-bucket",
					"binding": "screenshots_bucket",
					"remote": true,
				},
			],
		},
	},
}
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"

[[env.production.r2_buckets]]
bucket_name = "screenshots-bucket"
binding = "screenshots_bucket"

[[env.staging.r2_buckets]]
bucket_name = "preview-screenshots-bucket"
binding = "screenshots_bucket"
remote = true

Spouštění wrangler dev -e staging (nebo CLOUDFLARE_ENV=staging vite dev) s výše uvedenou konfigurací znamená, že:

Doporučujeme nakonfigurovat konkrétní bindings tak, aby se připojovaly ke svým vzdáleným protějškům. Tyto služby často závisí na síťové infrastruktuře Cloudflare, nebo mají komplexní backendy, které nelze lokálně plně simulovat.

U následujících bindings se doporučuje mít remote: true ve vaší konfiguraci Wrangler:

Browser Run:

Pro interakci se skutečným headless prohlížečem za účelem renderování. Pro Browser Run v současnosti neexistuje lokální simulace.

{
	"browser": {
		"binding": "MY_BROWSER",
		"remote": true
	},
}
[browser]
binding = "MY_BROWSER"
remote = true

Workers AI:

K využití skutečných modelů AI nasazených v síti Cloudflare pro inferenci. Pro Workers AI v současnosti neexistuje žádná místní simulace.

{
	"ai": {
		"binding": "AI",
		"remote": true
	},
}
[ai]
binding = "AI"
remote = true

Vectorize:

Chcete-li se připojit ke svým produkčním indexům Vectorize kvůli přesnému vektorovému vyhledávání a operacím podobnosti. Pro Vectorize v současnosti neexistuje žádná lokální simulace.

{
	"vectorize": [
		{
			"binding": "MY_VECTORIZE_INDEX",
			"index_name": "my-prod-index",
			"remote": true
		}
	],
}
[[vectorize]]
binding = "MY_VECTORIZE_INDEX"
index_name = "my-prod-index"
remote = true

mTLS:

K ověření, že proces výměny a validace certifikátů funguje podle očekávání. Pro bindings mTLS v současnosti neexistuje žádná místní simulace.

{
	"mtls_certificates": [
		{
			"binding": "MY_CLIENT_CERT_FETCHER",
			"certificate_id": "<YOUR_UPLOADED_CERT_ID>",
			"remote": true
			}
	]
}
[[mtls_certificates]]
binding = "MY_CLIENT_CERT_FETCHER"
certificate_id = "<YOUR_UPLOADED_CERT_ID>"
remote = true

Obrázky:

Chcete-li se připojit k věrné verzi Images API a ověřit, že všechny transformace fungují podle očekávání. Lokální simulace pro Cloudflare Images je omezené pouze na podmnožinu funkcí.

{
	"images": {
		"binding": "IMAGES" ,
		"remote": true
	}
}
[images]
binding = "IMAGES"
remote = true

Dispatch Namespaces:

Uživatelé Workers for Platforms mohou nakonfigurovat remote: true v definicích vazeb dispatch namespace:

{
	"dispatch_namespaces": [
		{
			"binding": "DISPATCH_NAMESPACE",
			"namespace": "testing",
			"remote":true
		}
	]
}
[[dispatch_namespaces]]
binding = "DISPATCH_NAMESPACE"
namespace = "testing"
remote = true

To vám umožňuje spustit váš dynamic dispatch Worker lokálně a přitom jej připojit k vaší vzdálené vazbě dispatch namespace. Díky tomu můžete testovat změny ve své hlavní logice dispatchování proti reálným, nasazeným uživatelské Workers.

Nepodporované vzdálené bindings

Určité bindings nejsou podporovány pro vzdálená připojení (tj. s remote: true) během lokálního vývoje. Ty vždy používají lokální simulace nebo lokální hodnoty.

Pokud remote: true je zadáno v konfiguraci Wrangler pro některý z následujících nepodporovaných typů bindings, Cloudflare vydá chybu. Viz všechny podporované a nepodporované vazby pro vzdálené vazby.

Použití vzdálených prostředků s Durable Objects a Workflows

Bindings pro Durable Object a Workflow aktuálně nemohou být remote, přesto je můžete používat při lokálním vývoji a nechat je pracovat se vzdálenými prostředky.

Pro toto jsou doporučeny dva vzory:

Důležité poznámky

Připojte se k Workers chráněným pomocí Access

Pokud je váš Worker chráněn Cloudflare Access, Wrangler se musí při připojování k vzdáleným vazbám ověřit pomocí Access. Platí to bez ohledu na to, zda Access chrání samotný Worker, všechny Workers v účtu, nebo workers.dev hostname, Custom Domain nebo jiný hostname či cestu, které směrují na Worker.

Existují dva způsoby, jak se můžete ověřit vůči Access:

Chcete-li nastavit ověřování pomocí Service Token:

  1. Vytvořte service token.

    V Cloudflare dashboardu přejděte na Zero Trust > Access > Service Auth > Service Tokens a vytvořte nový token. Viz Service tokens pro úplnou referenci. Zobrazí se vám Client ID a Client Secret, uložte si je na bezpečné místo, protože secret se znovu nezobrazí.

  2. Přidejte zásadu Service Auth do aplikace Access, která chrání váš Worker.

    Otevřete existující aplikaci Access, která již chrání Worker nebo hostname používaný pro vzdálené vazby, a připojte novou zásadu pomocí:

    • Akce: Service Auth
    • Include: Token služby, který jste vytvořili, nebo možnost "Any Access Service Token", pokud chcete povolit přístup k Workeru libovolnému tokenu služby.

  3. Zpřístupněte přihlašovací údaje Wrangleru.

    Nastavte CLOUDFLARE_ACCESS_CLIENT_ID a CLOUDFLARE_ACCESS_CLIENT_SECRET systémové proměnné prostředí v prostředí, ve kterém běží Wrangler:

    export CLOUDFLARE_ACCESS_CLIENT_ID=<CLIENT_ID>
export CLOUDFLARE_ACCESS_CLIENT_SECRET=<CLIENT_SECRET>

    V CI ukládejte hodnoty jako secrets a zpřístupněte je jako proměnné prostředí kroku, který spouští Wrangler.

API

Wrangler poskytuje programové nástroje, které autorům vývojářských nástrojů pomáhají podporovat vzdálená připojení bindingů při spouštění kódu Workers pomocí Miniflare.

Mezi klíčová API patří:

startRemoteProxySession

Tato funkce spustí proxy relaci pro danou sadu vazeb. Přijímá možnosti pro řízení chování relace, včetně auth možnost s ID účtu Cloudflare a API tokenem pro přístup přes remote binding.

Vrací objekt s:

unstable_convertConfigBindingsToStartWorkerBindings

unstable_readConfig nástroj vrací Unstable_Config objekt, který obsahuje definici bindingů uvedených v konfiguračním souboru. Tyto definice bindingů však nejsou přímo kompatibilní s startRemoteProxySession. Přesto může být praktické číst deklarace bindings pomocí unstable_readConfig a poté předejte je startRemoteProxySession, proto pro tento účel wrangler zpřístupňuje unstable_convertConfigBindingsToStartWorkerBindings což je jednoduchý nástroj pro převod bindingů v Unstable_Config objekt do struktury, kterou lze předat do startRemoteProxySession.

maybeStartOrUpdateRemoteProxySession

Tento wrapper zjednodušuje správu proxy relací. Přijímá:

Vrací objekt s podrobnostmi o proxy relaci, pokud byla spuštěna nebo aktualizována, nebo null pokud není potřeba proxy relace.

Funkce:

Příklad

Následuje základní příklad použití Miniflare s maybeStartOrUpdateRemoteProxySession pro poskytnutí lokální vývojové relace se vzdálenými bindings. Tento příklad používá jeden pevně zadaný KV binding.

import { Miniflare, MiniflareOptions } from "miniflare";
import { maybeStartOrUpdateRemoteProxySession } from "wrangler";

let mf;

let remoteProxySessionDetails = null;

async function startOrUpdateDevSession() {
	remoteProxySessionDetails = await maybeStartOrUpdateRemoteProxySession(
		{
			bindings: {
				MY_KV: {
					type: "kv_namespace",
					id: "kv-id",
					remote: true,
				},
			},
		},
		remoteProxySessionDetails,
	);

	const miniflareOptions = {
		scriptPath: "./worker.js",
		kvNamespaces: {
			MY_KV: {
				id: "kv-id",
				remoteProxyConnectionString:
					remoteProxySessionDetails?.session.remoteProxyConnectionString,
			},
		},
	};

	if (!mf) {
		mf = new Miniflare(miniflareOptions);
	} else {
		mf.setOptions(miniflareOptions);
	}
}

// ... tool logic that invokes `startOrUpdateDevSession()` ...

// ... once the dev session is no longer needed run
// `remoteProxySessionDetails?.session.dispose()`
import { Miniflare, MiniflareOptions } from "miniflare";
import { maybeStartOrUpdateRemoteProxySession } from "wrangler";

let mf: Miniflare | null;

let remoteProxySessionDetails: Awaited<
	ReturnType<typeof maybeStartOrUpdateRemoteProxySession>
> | null = null;

async function startOrUpdateDevSession() {
	remoteProxySessionDetails = await maybeStartOrUpdateRemoteProxySession(
		{
			bindings: {
				MY_KV: {
					type: "kv_namespace",
					id: "kv-id",
					remote: true,
				},
			},
		},
		remoteProxySessionDetails,
	);

	const miniflareOptions: MiniflareOptions = {
		scriptPath: "./worker.js",
		kvNamespaces: {
			MY_KV: {
				id: "kv-id",
				remoteProxyConnectionString:
					remoteProxySessionDetails?.session.remoteProxyConnectionString,
			},
		},
	};

	if (!mf) {
		mf = new Miniflare(miniflareOptions);
	} else {
		mf.setOptions(miniflareOptions);
	}
}

// ... tool logic that invokes `startOrUpdateDevSession()` ...

// ... once the dev session is no longer needed run
// `remoteProxySessionDetails?.session.dispose()`

wrangler dev --remote (Legacy)

Kromě lokálního vývoje poháněného nástrojem Miniflare nabízí Wrangler také plně vzdálený režim vývoje pomocí wrangler dev --remote. Vzdálený vývoj je ne podporováno v pluginu Vite.

npx wrangler dev --remote

Během vzdálený vývoj, veškerý kód vašeho Workeru se nahraje do dočasného náhledového prostředí v infrastruktuře Cloudflare a změny v kódu se automaticky nahrávají při každém uložení.

Při vzdáleném vývoji se všechny bindings automaticky připojují ke svým vzdáleným prostředkům. Na rozdíl od lokálního vývoje nelze bindings nakonfigurovat tak, aby používaly lokální simulace, vždy použijí nasazené prostředky v síti Cloudflare.

Kdy použít vzdálený vývoj

Co zvážit

Omezení