INTEGRITY Dokumentace

← Cloudflare Workers / workers / wrangler

Konfigurace

Wrangler může volitelně použít konfigurační soubor k přizpůsobení nastavení vývoje a nasazení Workeru.

Je osvědčeným postupem považovat konfigurační soubor Wrangler za zdroj pravdy pro konfiguraci Worker.

Ukázková konfigurace Wrangler

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	// Top-level configuration
	"name": "my-worker",
	"main": "src/index.js",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"workers_dev": false,
	"route": {
		"pattern": "example.org/*",
		"zone_name": "example.org",
	},
	"kv_namespaces": [
		{
			"binding": "<MY_NAMESPACE>",
			"id": "<KV_ID>",
		},
	],
	"env": {
		"staging": {
			"name": "my-worker-staging",
			"route": {
				"pattern": "staging.example.org/*",
				"zone_name": "example.org",
			},
			"kv_namespaces": [
				{
					"binding": "<MY_NAMESPACE>",
					"id": "<STAGING_KV_ID>",
				},
			],
		},
	},
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
main = "src/index.js"
# Set this to today's date
compatibility_date = "2026-08-28"
workers_dev = false

[route]
pattern = "example.org/*"
zone_name = "example.org"

[[kv_namespaces]]
binding = "<MY_NAMESPACE>"
id = "<KV_ID>"

[env.staging]
name = "my-worker-staging"

  [env.staging.route]
  pattern = "staging.example.org/*"
  zone_name = "example.org"

  [[env.staging.kv_namespaces]]
  binding = "<MY_NAMESPACE>"
  id = "<STAGING_KV_ID>"

Prostředí

Různé konfigurace pro Worker můžete definovat pomocí Wrangleru prostředí. Existuje výchozí (nejvyšší úrovně) prostředí a dále můžete vytvářet pojmenovaná prostředí s konfigurací specifickou pro dané prostředí.

Jsou definovány v [env.<name>] klíče, jako je [env.staging] který pak můžete zobrazit v náhledu nebo nasadit pomocí -e / --env příznak v wrangler příkazy jako npx wrangler deploy --env staging.

Většinu klíčů lze dědit, což znamená, že konfiguraci nejvyšší úrovně lze použít i v prostředích. Bindings, jako je vars nebo kv_namespaces, nejsou dědičné a je nutné je definovat explicitně.

Kromě toho existuje několik klíčů, které mohou pouze se zobrazí na nejvyšší úrovni.

Automatické zajišťování

Beta

Wrangler dokáže při nasazení Workeru automaticky vytvořit potřebné prostředky, aniž byste je museli připravovat předem.

V současnosti to funguje pro následující prostředky: KV, R2, D1, Flagship, AI Search, Agent Memory, Dispatch Namespaces a Queues.

Chcete-li tuto funkci použít, přidejte do konfiguračního souboru bindings bez přidáním ID prostředků, nebo v případě R2 názvu bucketu. Prostředky budou vytvořeny s předponou tvořenou názvem vašeho workeru.

{
	"kv_namespaces": [
		{
			"binding": "<MY_KV_NAMESPACE>",
		},
	],
}
[[kv_namespaces]]
binding = "<MY_KV_NAMESPACE>"

Když spustíte wrangler dev, automaticky se vytvoří lokální prostředky, které zůstanou zachovány mezi jednotlivými spuštěními. Když spustíte wrangler deploy, prostředky se pro vás vytvoří a jejich ID se zapíší zpět do vašeho konfiguračního souboru.

Pokud nasadíte worker s prostředky bez ID prostředků z dashboardu (například přes GitHub), prostředky se vytvoří, ale jejich ID budou dostupná pouze přes dashboard. V současnosti se tato ID prostředků nezapisují zpět do repozitáře.

Klíče pouze nejvyšší úrovně

Klíče nejvyšší úrovně platí pro Worker jako celek (a tedy pro všechna prostředí). Nelze je definovat v rámci pojmenovaných prostředí.

Dědičné klíče

Dědičné klíče lze nastavit na nejvyšší úrovni a mohou být zděděny (nebo přepsány) konfigurací specifickou pro dané prostředí.

Neděditelné klíče

Neděditelné klíče lze nastavit na nejvyšší úrovni, nelze je však zdědit v prostředích a musí být zadány zvlášť pro každé prostředí.

Typy tras

Existují tři typy trasy: Custom Domains, trasy, a workers.dev.

Custom Domains

Custom Domains umožňují připojit váš Worker k doméně nebo subdoméně, aniž byste museli měnit nastavení DNS nebo spravovat certifikáty.

Příklad:

{
	"routes": [
		{
			"pattern": "shop.example.com",
			"custom_domain": true,
		},
	],
}
[[routes]]
pattern = "shop.example.com"
custom_domain = true

Trasy

Trasy umožňují uživatelům namapovat vzor URL adresy na Worker. Trasu lze nakonfigurovat jako trasu podle ID zóny, trasu podle názvu zóny nebo jako jednoduchou trasu.

Trasa Zone ID

Příklad:

{
	"routes": [
		{
			"pattern": "subdomain.example.com/*",
			"zone_id": "<YOUR_ZONE_ID>",
		},
	],
}
[[routes]]
pattern = "subdomain.example.com/*"
zone_id = "<YOUR_ZONE_ID>"

Trasa podle názvu zóny

Příklad:

{
	"routes": [
		{
			"pattern": "subdomain.example.com/*",
			"zone_name": "example.com",
		},
	],
}
[[routes]]
pattern = "subdomain.example.com/*"
zone_name = "example.com"

Jednoduchá trasa

Toto je jednoduchá route, která vyžaduje pouze pattern.

Příklad:

{
	"route": "example.com/*",
}
route = "example.com/*"

workers.dev

Účty Cloudflare Workers obsahují workers.dev subdoména, kterou lze nakonfigurovat v Cloudflare dashboardu.

{
	"workers_dev": false,
}
workers_dev = false

Triggery

Triggery vám umožňují definovat cron výraz pro vyvolání vašeho Workeru scheduled funkci. Viz Podporované výrazy cron.

Příklad:

{
	"triggers": {
		"crons": ["* * * * *"],
	},
}
[triggers]
crons = [ "* * * * *" ]

Observabilita

Observabilita nastavení vám umožňuje automaticky přijímat, ukládat, filtrovat a analyzovat protokolová data odesílaná z Cloudflare Workers přímo z dashboardu vašeho Cloudflare Workeru.

Příklad:

{
	"observability": {
		"enabled": true,
		"head_sampling_rate": 0.1, // 10% of requests are logged
	},
}
[observability]
enabled = true
head_sampling_rate = 0.1

Vlastní sestavení

Můžete nakonfigurovat vlastní krok sestavení, který se spustí před nasazením Workeru. Podrobnosti najdete v Vlastní sestavení.

Příklad:

{
	"build": {
		"command": "npm run build",
		"cwd": "build_cwd",
		"watch_dir": "build_watch_dir",
	},
}
[build]
command = "npm run build"
cwd = "build_cwd"
watch_dir = "build_watch_dir"

Limity

Chování svého Workeru můžete za běhu omezit. Limity jsou podporovány pouze pro Model využití Standard. Limity se vynucují pouze po nasazení do sítě Cloudflare, nikoli při lokálním vývoji. Limit CPU lze nastavit maximálně na 300,000 milisekund (5 minut).

Každý izolát má určitou vestavěnou flexibilitu pro případy, kdy váš Worker příležitostně překročí nastavený limit. Pokud váš Worker začne limit překračovat trvale, jeho spuštění bude ukončeno podle nastaveného limitu.


Příklad:

{
	"limits": {
		"cpu_ms": 100,
		"subrequests": 150,
	},
}
[limits]
cpu_ms = 100
subrequests = 150

Bindings

Browser Run

Workers Browser Run API umožňuje vývojářům programově ovládat instanci headless prohlížeče a interagovat s ní a vytvářet automatizační postupy pro své aplikace a produkty.

A vazba pro prohlížeč poskytne vašemu Workeru autentizovaný koncový bod pro komunikaci s vyhrazenou instancí prohlížeče Chromium.

Příklad:

{
	"browser": {
		"binding": "<BINDING_NAME>",
	},
}
[browser]
binding = "<BINDING_NAME>"

Databáze D1

D1 je bezserverová SQL databáze od Cloudflare. Worker může dotazovat databázi D1 (nebo databáze) vytvořením binding ke každé databázi pro D1 Workers Binding API.

Chcete-li k Workeru připojit databáze D1, přiřaďte pole níže uvedeného objektu do [[d1_databases]] klíč.

Příklad:

{
	"d1_databases": [
		{
			"binding": "<BINDING_NAME>",
			"database_name": "<DATABASE_NAME>",
			"database_id": "<DATABASE_ID>",
		},
	],
}
[[d1_databases]]
binding = "<BINDING_NAME>"
database_name = "<DATABASE_NAME>"
database_id = "<DATABASE_ID>"

Vazby pro dispatch namespace (Workers for Platforms)

Vazby dispatch namespace umožňují komunikaci mezi dynamic dispatch Worker a dispatch namespace. Vazby dispatch namespace se používají v Workers for Platforms. Workers for Platforms vám pomáhá programově nasazovat serverless funkce jménem vašich zákazníků.

{
	"dispatch_namespaces": [
		{
			"binding": "<BINDING_NAME>",
			"namespace": "<NAMESPACE_NAME>",
			"outbound": {
				"service": "<WORKER_NAME>",
				"parameters": ["params_object"],
			},
		},
	],
}
[[dispatch_namespaces]]
binding = "<BINDING_NAME>"
namespace = "<NAMESPACE_NAME>"

  [dispatch_namespaces.outbound]
  service = "<WORKER_NAME>"
  parameters = [ "params_object" ]

Durable Objects

Durable Objects poskytují koordinaci s nízkou latencí a konzistentní úložiště pro platformu Workers.

Chcete-li k Workeru připojit Durable Objects, přiřaďte pole níže uvedeného objektu do durable_objects.bindings klíč.

Příklad:

{
	"durable_objects": {
		"bindings": [
			{
				"name": "<BINDING_NAME>",
				"class_name": "<CLASS_NAME>",
			},
		],
	},
}
[[durable_objects.bindings]]
name = "<BINDING_NAME>"
class_name = "<CLASS_NAME>"

Exporty

exports pole deklaruje třídy Durable Object, které tento Worker exportuje, a jejich stav životního cyklu. Viz Exporty tříd Durable Object.

Každá položka v exports je indexováno podle názvu třídy Durable Object. Pole jednotlivých položek jsou:

Příklad:

{
	"exports": {
		"MyDurableObject": {
			"type": "durable-object",
			"storage": "sqlite",
		},
		"OldClass": {
			"type": "durable-object",
			"state": "deleted",
		},
		"OldName": {
			"type": "durable-object",
			"state": "renamed",
			"renamed_to": "NewName",
		},
		"NewName": {
			"type": "durable-object",
			"storage": "sqlite",
		},
	},
}
[exports.MyDurableObject]
type = "durable-object"
storage = "sqlite"

[exports.OldClass]
type = "durable-object"
state = "deleted"

[exports.OldName]
type = "durable-object"
state = "renamed"
renamed_to = "NewName"

[exports.NewName]
type = "durable-object"
storage = "sqlite"

Migrace

Při provádění změn ve třídách Durable Object u Workeru, který používá starší migrations pole, musíte provést migraci. Více informací najdete v Migrace tříd Durable Object (zastaralé).

Příklad:

{
	"migrations": [
		{
			"tag": "v1",
			"new_sqlite_classes": [
				// Array of new classes
				"DurableObjectExample",
			],
		},
		{
			"tag": "v2", // Should be unique for each entry
			"renamed_classes": [
				// Array of rename directives
				{
					"from": "DurableObjectExample",
					"to": "UpdatedName",
				},
			],
			"deleted_classes": [
				// Array of deleted class names
				"DeprecatedClass",
			],
		},
	],
}
[[migrations]]
tag = "v1"
new_sqlite_classes = [ "DurableObjectExample" ]

[[migrations]]
tag = "v2"
deleted_classes = [ "DeprecatedClass" ]

  [[migrations.renamed_classes]]
  from = "DurableObjectExample"
  to = "UpdatedName"

e-mailové vazby

Ze svého Workeru můžete odeslat e-mail o jeho aktivitě na e-mailovou adresu ověřenou na Email Routing. Hodí se to například tehdy, když chcete vědět o spuštění určitých typů událostí.

Než budete moci k Workeru navázat e-mailovou adresu, musíte povolit Email Routing a mít alespoň jeden ověřená e-mailová adresa. Poté objektu (send_email) přiřaďte pole s typem email bindingu, který potřebujete.

Do souboru Wrangler můžete přidat jeden nebo více typů bindingů. Každý atribut ale musí být na samostatném řádku:

{
	"send_email": [
		{
			"name": "<NAME_FOR_BINDING1>"
		},
		{
			"name": "<NAME_FOR_BINDING2>",
			"destination_address": "<YOUR_EMAIL>@example.com"
		},
		{
			"name": "<NAME_FOR_BINDING3>",
			"allowed_destination_addresses": [
				"<YOUR_EMAIL>@example.com",
				"<YOUR_EMAIL2>@example.com"
			]
		}
	]
}
[[send_email]]
name = "<NAME_FOR_BINDING1>"

[[send_email]]
name = "<NAME_FOR_BINDING2>"
destination_address = "<YOUR_EMAIL>@example.com"

[[send_email]]
name = "<NAME_FOR_BINDING3>"
allowed_destination_addresses = [ "<YOUR_EMAIL>@example.com", "<YOUR_EMAIL2>@example.com" ]

Proměnné prostředí

Proměnné prostředí jsou typem vazby, která vám umožňuje připojit k Workeru textové řetězce nebo hodnoty JSON.

Příklad:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker-dev",
	"vars": {
		"API_HOST": "example.com",
		"API_ACCOUNT_ID": "example_user",
		"SERVICE_X_DATA": {
			"URL": "service-x-api.dev.example",
			"MY_ID": 123
		}
	}
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker-dev"

[vars]
API_HOST = "example.com"
API_ACCOUNT_ID = "example_user"

  [vars.SERVICE_X_DATA]
  URL = "service-x-api.dev.example"
  MY_ID = 123

Hyperdrive

Hyperdrive bindingy vám umožňují interagovat s libovolnou databází Postgres a dotazovat se do ní přímo z Workeru.

Příklad:

{
	// required for database drivers to function
	"compatibility_flags": ["nodejs_compat_v2"],
	"hyperdrive": [
		{
			"binding": "<BINDING_NAME>",
			"id": "<ID>",
		},
	],
}
compatibility_flags = [ "nodejs_compat_v2" ]

[[hyperdrive]]
binding = "<BINDING_NAME>"
id = "<ID>"

Obrázky

Cloudflare Images vám umožňuje odesílat transformační požadavky pro optimalizaci, změnu velikosti a úpravu obrázků uložených ve vzdálených zdrojích.

Chcete-li k Workeru připojit Images, přiřaďte pole níže uvedeného objektu do images klíč.

binding (povinné). Název vazby (binding) použité k odkazování na Images API.

{
	"images": {
		"binding": "IMAGES", // i.e. available in your Worker on env.IMAGES
	},
}
[images]
binding = "IMAGES"

KV namespaces

Workers KV je globální úložiště dat typu klíč-hodnota s nízkou latencí. Ukládá data v malém počtu centralizovaných datových center a po přístupu je poté ukládá do mezipaměti v datových centrech Cloudflare.

Chcete-li k Workeru připojit KV namespaces, přiřaďte pole níže uvedeného objektu do kv_namespaces klíč.

Příklad:

{
	"kv_namespaces": [
		{
			"binding": "<BINDING_NAME1>",
			"id": "<NAMESPACE_ID1>",
		},
		{
			"binding": "<BINDING_NAME2>",
			"id": "<NAMESPACE_ID2>",
		},
	],
}
[[kv_namespaces]]
binding = "<BINDING_NAME1>"
id = "<NAMESPACE_ID1>"

[[kv_namespaces]]
binding = "<BINDING_NAME2>"
id = "<NAMESPACE_ID2>"

Namespaces AI Search

AI Search je spravovaná vyhledávací služba Cloudflare. namespace je logické seskupení instancí AI Search. Binding uděluje plný přístup ke všem instancím v rámci namespace.

Chcete-li k Workeru připojit AI Search namespaces, přiřaďte pole níže uvedeného objektu do ai_search_namespaces klíč.

Příklad:

{
	"ai_search_namespaces": [
		{
			"binding": "<BINDING_NAME>",
			"namespace": "default",
		},
	],
}
[[ai_search_namespaces]]
binding = "<BINDING_NAME>"
namespace = "default"

Instance AI Search

Chcete-li se připojit přímo k již existujícímu AI Search instance v výchozí namespace, přiřaďte pole níže uvedeného objektu k ai_search klíč. Tato vazba nepodporuje operace na úrovni namespace, jako je list(), create(), nebo delete().

Příklad:

{
	"ai_search": [
		{
			"binding": "<BINDING_NAME>",
			"instance_name": "<INSTANCE_NAME>",
		},
	],
}
[[ai_search]]
binding = "<BINDING_NAME>"
instance_name = "<INSTANCE_NAME>"

Queues

Queues je globální služba pro frontování zpráv od Cloudflare, poskytující zaručené doručení a dávkování zpráv. Chcete-li pracovat s frontou pomocí Workers, potřebujete producer Worker, který bude odesílat zprávy do fronty, a consumer Worker, který bude z fronty stahovat dávky zpráv. Jeden Worker může zprávy produkovat do více front i konzumovat z více front zároveň.

Chcete-li k Workeru typu producer připojit Queues, přiřaďte pole níže uvedeného objektu do [[queues.producers]] klíč.

Příklad:

{
	"queues": {
		"producers": [
			{
				"binding": "<BINDING_NAME>",
				"queue": "<QUEUE_NAME>",
				"delivery_delay": 60, // Delay messages by 60 seconds before they are delivered to a consumer
			},
		],
	},
}
[[queues.producers]]
binding = "<BINDING_NAME>"
queue = "<QUEUE_NAME>"
delivery_delay = 60

Chcete-li k Workeru typu consumer připojit Queues, přiřaďte pole níže uvedeného objektu do [[queues.consumers]] klíč.

Příklad:

{
	"queues": {
		"consumers": [
			{
				"queue": "my-queue",
				"max_batch_size": 10,
				"max_batch_timeout": 30,
				"max_retries": 10,
				"dead_letter_queue": "my-queue-dlq",
				"max_concurrency": 5,
				"retry_delay": 120, // Delay retried messages by 2 minutes before re-attempting delivery
			},
		],
	},
}
[[queues.consumers]]
queue = "my-queue"
max_batch_size = 10
max_batch_timeout = 30
max_retries = 10
dead_letter_queue = "my-queue-dlq"
max_concurrency = 5
retry_delay = 120

R2 buckety

Cloudflare R2 Storage umožňuje vývojářům ukládat velké objemy nestrukturovaných dat bez nákladných poplatků za odchozí přenos dat (egress), které jsou typické pro běžné cloudové úložné služby.

Chcete-li k Workeru připojit buckety R2, přiřaďte pole níže uvedeného objektu do r2_buckets klíč.

Příklad:

{
	"r2_buckets": [
		{
			"binding": "<BINDING_NAME1>",
			"bucket_name": "<BUCKET_NAME1>",
		},
		{
			"binding": "<BINDING_NAME2>",
			"bucket_name": "<BUCKET_NAME2>",
		},
	],
}
[[r2_buckets]]
binding = "<BINDING_NAME1>"
bucket_name = "<BUCKET_NAME1>"

[[r2_buckets]]
binding = "<BINDING_NAME2>"
bucket_name = "<BUCKET_NAME2>"

Vectorize indexy

A Vectorize index umožňuje vkládat a dotazovat vektorové embeddingy pro sémantické vyhledávání, klasifikaci a další případy použití vektorového vyhledávání.

Chcete-li k Workeru připojit indexy Vectorize, přiřaďte pole níže uvedeného objektu do vectorize klíč.

Příklad:

{
	"vectorize": [
		{
			"binding": "<BINDING_NAME>",
			"index_name": "<INDEX_NAME>",
		},
	],
}
[[vectorize]]
binding = "<BINDING_NAME>"
index_name = "<INDEX_NAME>"

Service bindings

Service binding umožňuje odesílat HTTP požadavky jinému Workeru, aniž by tyto požadavky procházely internetem. Požadavek okamžitě zavolá navazující Worker, čímž se sníží latence ve srovnání s požadavkem na službu třetí strany. Viz O Service Bindings.

Chcete-li k Workeru připojit jiné Workers, přiřaďte pole níže uvedeného objektu do services klíč.

Příklad:

{
	"services": [
		{
			"binding": "<BINDING_NAME>",
			"service": "<WORKER_NAME>",
			"entrypoint": "<ENTRYPOINT_NAME>",
		},
	],
}
[[services]]
binding = "<BINDING_NAME>"
service = "<WORKER_NAME>"
entrypoint = "<ENTRYPOINT_NAME>"

Statické prostředky

Viz Assets.

Analytics Engine Datasets

Workers Analytics Engine poskytuje analytiku, observabilitu a záznam dat z Workers. Zapisujte datové body do vazby (binding) svého Workeru a poté data dotazujte pomocí SQL API.

Chcete-li k Workeru připojit Analytics Engine datasets, přiřaďte pole níže uvedeného objektu do analytics_engine_datasets klíč.

Příklad:

{
	"analytics_engine_datasets": [
		{
			"binding": "<BINDING_NAME>",
			"dataset": "<DATASET_NAME>",
		},
	],
}
[[analytics_engine_datasets]]
binding = "<BINDING_NAME>"
dataset = "<DATASET_NAME>"

Certifikáty mTLS

Chcete-li komunikovat s originy, které vyžadují ověření klienta, může Worker v subpožadavcích předložit certifikát pro mTLS. Wrangler poskytuje mtls-certificate příkaz k nahrávání a správě těchto certifikátů.

Chcete-li vytvořit binding na certifikát mTLS pro váš Worker, přiřaďte pole objektů s následující strukturou do mtls_certificates klíč.

Příklad konfiguračního souboru Wrangler, který obsahuje vazbu na certifikát mTLS:

{
	"mtls_certificates": [
		{
			"binding": "<BINDING_NAME1>",
			"certificate_id": "<CERTIFICATE_ID1>",
		},
		{
			"binding": "<BINDING_NAME2>",
			"certificate_id": "<CERTIFICATE_ID2>",
		},
	],
}
[[mtls_certificates]]
binding = "<BINDING_NAME1>"
certificate_id = "<CERTIFICATE_ID1>"

[[mtls_certificates]]
binding = "<BINDING_NAME2>"
certificate_id = "<CERTIFICATE_ID2>"

Bindingy certifikátů mTLS lze pak za běhu použít ke komunikaci se zabezpečenými originy prostřednictvím jejich fetch metoda.

Workers AI

Workers AI umožňuje spouštět modely strojového učení v síti Cloudflare přímo z vašeho vlastního kódu, ať už z Workers, Pages nebo odkudkoli přes REST API.

Na rozdíl od ostatních bindings je tento binding omezen na jeden AI binding na projekt Workeru.

Příklad:

{
	"ai": {
		"binding": "AI", // available in your Worker code on `env.AI`
	},
}
[ai]
binding = "AI"

Workflows

Workflows umožňují vytvářet trvalé, vícekrokové aplikace na platformě Workers. Binding Workflow umožňuje vašemu Workeru programově vytvářet instance Workflow a spravovat je.

Chcete-li k Workeru připojit Workflows, přiřaďte pole níže uvedeného objektu do workflows klíč.

Příklad:

{
	"workflows": [
		{
			"binding": "<BINDING_NAME>",
			"name": "<WORKFLOW_NAME>",
			"class_name": "<CLASS_NAME>",
		},
	],
}
[[workflows]]
binding = "<BINDING_NAME>"
name = "<WORKFLOW_NAME>"
class_name = "<CLASS_NAME>"

Assets

Statické prostředky umožňuje vývojářům provozovat frontendové weby na Workers. Můžete nakonfigurovat adresář assetů, volitelný runtime binding a možnosti konfigurace směrování.

Pro jeden Worker můžete nakonfigurovat pouze jednu kolekci assets.

Následující možnosti jsou k dispozici v části assets klíč.

Příklad:

{
	"assets": {
		"directory": "./public",
		"binding": "ASSETS",
		"html_handling": "force-trailing-slash",
		"not_found_handling": "404-page",
	},
}
[assets]
directory = "./public"
binding = "ASSETS"
html_handling = "force-trailing-slash"
not_found_handling = "404-page"

Můžete také nakonfigurovat run_worker_first polem vzorů tras:

{
	"assets": {
		"directory": "./public",
		"binding": "ASSETS",
		"run_worker_first": [
			"/api/*", // API calls go to Worker first
			"!/api/docs/*", // EXCEPTION: For /api/docs/*, try static assets first
		],
	},
}
[assets]
directory = "./public"
binding = "ASSETS"
run_worker_first = [ "/api/*", "!/api/docs/*" ]

Containers

Můžete definovat Containers pro spuštění vedle vašeho Workeru pomocí containers .

K dispozici jsou následující možnosti:

{
	"containers": [
		{
			"class_name": "MyContainer",
			"image": "./Dockerfile",
			"max_instances": 10,
			"instance_type": "basic", // Optional, defaults to "lite"
			"image_vars": {
				"FOO": "BAR",
			},
			"constraints": {
				"regions": ["ENAM", "WNAM"],
				"jurisdiction": "fedramp",
			},
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"name": "MY_CONTAINER",
				"class_name": "MyContainer",
			},
		],
	},
	"migrations": [
		{
			"tag": "v1",
			"new_sqlite_classes": ["MyContainer"],
		},
	],
}
[[containers]]
class_name = "MyContainer"
image = "./Dockerfile"
max_instances = 10
instance_type = "basic"

  [containers.image_vars]
  FOO = "BAR"

  [containers.constraints]
  regions = [ "ENAM", "WNAM" ]
  jurisdiction = "fedramp"

[[durable_objects.bindings]]
name = "MY_CONTAINER"
class_name = "MyContainer"

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "MyContainer" ]

Vlastní typy instancí

Místo pojmenované typy instancí, můžete nastavit vlastní typ instance samostatným nastavením vCPU, paměti a disku. Podrobnosti najdete v dokumentace k limitům pro omezení vlastních typů instancí.

K dispozici jsou následující možnosti:

{
	"containers": [
		{
			"image": "./Dockerfile",
			"instance_type": {
				"vcpu": 1,
				"memory_mib": 1024,
				"disk_mb": 4000,
			},
		},
	],
}
[[containers]]
image = "./Dockerfile"

  [containers.instance_type]
  vcpu = 1
  memory_mib = 1_024
  disk_mb = 4_000

SSH

Konfigurace přístupu SSH k instanci Container přes Wrangler. Návod k připojení ke Containers přes SSH najdete v SSH.

K dispozici jsou následující možnosti:

Autorizované klíče

Autorizovaný klíč je veřejný klíč, který lze použít k připojení přes SSH do Containeru.

Následující jsou vlastnosti klíče:

Bundling

Wrangler může fungovat ve dvou režimech: výchozím režimu bundlingu a --no-bundle režim. V režimu sdružování (bundling) Wrangler projde všechny importy vašeho kódu a vygeneruje jeden JavaScript soubor "entry-point". Importovaný zdrojový kód je do tohoto souboru entry-point "vložen/sloučen" (inlined/bundled).

Do Workeru je také možné zahrnout další moduly, které se nahrají společně se vstupním bodem (entry point). Které další moduly se mají do Workeru zahrnout, určíte pomocí rules klíč, díky kterému budou tyto moduly dostupné k importu při vyvolání vašeho Workeru. Klíč rules klíč bude pole níže uvedeného objektu.

Příklad:

{
	"rules": [
		{
			"type": "Text",
			"globs": ["**/*.md"],
			"fallthrough": true,
		},
	],
}
[[rules]]
type = "Text"
globs = [ "**/*.md" ]
fallthrough = true

Import modulů uvnitř Workeru

Tyto moduly můžete ve svém Workeru importovat a odkazovat se na ně takto:

index.js
import markdown from "./example.md";

export default {
	async fetch() {
		return new Response(markdown);
	},
};

Najděte další moduly

Wrangler obvykle zahrne pouze další moduly, které jsou ve vašem zdrojovém kódu staticky importovány, jak je uvedeno ve výše uvedeném příkladu. Nastavením find_additional_modules na true ve vašem konfiguračním souboru, Wrangler projde strom souborů pod base_dir. Všechny soubory, které odpovídají rules bude také zahrnut jako nesbalený, externí modul v nasazeném Workeru. base_dir má jako výchozí adresář obsahující main vstupní bod.

Viz https://developers.cloudflare.com/workers/wrangler/bundling/ ↗ další podrobnosti a příklady.

Python Workers

Ve výchozím nastavení Python Workers sloučí soubory a složky v python_modules v kořenovém adresáři vašeho Workeru (vedle konfiguračního souboru wrangler). Soubory v tomto adresáři představují vaše vendorované balíčky, kam je nástroj pywrangler kopíruje. V některých případech se může stát, že soubory v této složce jsou příliš velké, a pokud je váš worker nepotřebuje, jen zbytečně zvětšují velikost balíčku.

Chcete-li to vyřešit, můžete některé soubory ze zahrnutí vyloučit. K tomu použijte python_modules.excludes možnost, například:

{
	"python_modules": {
		"excludes": ["**/*.pyc", "**/__pycache__"],
	},
}
[python_modules]
excludes = [ "**/*.pyc", "**/__pycache__" ]

Tímto se vyloučí veškeré soubory .pyc a __pycache__ adresáře uvnitř libovolného podadresáře v python_modules.

Standardně python_modules.excludes je nastaveno na ["**/*.pyc"], nezapomeňte to proto uvést, když nastavujete jinou hodnotu.

Nastavení lokálního vývoje

Můžete nakonfigurovat různé aspekty lokálního vývoje, například lokální protokol nebo port.

{
	"dev": {
		"ip": "192.168.1.1",
		"port": 8080,
		"local_protocol": "http",
	},
}
[dev]
ip = "192.168.1.1"
port = 8_080
local_protocol = "http"

Tajné klíče

Tajné klíče jsou typem bindingu, který vám umožňuje připojení šifrovaných textových hodnot do vašeho Workeru.

secrets konfigurační vlastnost

secrets konfigurační vlastnost umožňuje deklarovat názvy tajných hodnot, které váš Worker vyžaduje, v konfiguračním souboru Wrangler. Požadované tajné hodnoty se ověřují během lokálního vývoje a nasazení a slouží jako zdroj pravdy pro generování typů.

{
	"secrets": {
		"required": ["API_KEY", "DB_PASSWORD"],
	},
}
[secrets]
required = [ "API_KEY", "DB_PASSWORD" ]

Generování typů

Když secrets je definována na jakékoli úrovni konfigurace, wrangler types generuje typované vazby z názvů uvedených v secrets.required a už neodvozuje názvy tajných klíčů (secrets) z .dev.vars nebo .env soubory. Díky tomu můžete spouštět generování typů i v prostředích, kde tyto soubory nejsou k dispozici.

Podporují se secrets pro jednotlivá prostředí. Každé pojmenované prostředí vytváří vlastní rozhraní a agregovaný Env typ označuje secrets, které se objevují jen v některých prostředích, jako nepovinné.

Nasadit

Když secrets je definována, wrangler deploy a wrangler versions upload ověřte, že všechny secrets v secrets.required jsou u Workeru nastavené ještě před dokončením operace. Pokud některé požadované secrets chybí, příkaz selže a chybová zpráva uvede, které secrets je třeba nastavit.

Lokální vývoj

Uložte secrets pro použití při lokálním vývoji buď do .dev.vars soubor nebo .env soubor ve stejném adresáři jako konfigurační soubor Wrangleru.

Tyto soubory by měly být formátovány pomocí dotenv ↗ syntax. Například:

.dev.vars / .env
SECRET_KEY="value"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

Chcete-li nastavit různé tajné klíče pro každé prostředí Cloudflare, vytvořte soubory s názvem .dev.vars.<environment-name> nebo .env.<environment-name>.

Když v lokálním vývoji vyberete prostředí Cloudflare, načte se nejprve soubor specifický pro dané prostředí, a to před obecným .dev.vars (nebo .env) soubor.

Aliasing modulů

Wrangler můžete nakonfigurovat tak, aby všechna volání importu určitého balíčku nahradil modulem podle vašeho výběru, a to nakonfigurováním alias pole:

{
	"alias": {
		"foo": "./replacement-module-filepath",
	},
}
[alias]
foo = "./replacement-module-filepath"
replacement-module-filepath.js
export const bar = "baz";

S výše uvedenou konfigurací se jakákoli volání na import nebo require() modul foo se bude aliasovat tak, aby ukazoval na váš náhradní modul:

import { bar } from "foo";

console.log(bar); // returns "baz"

Problémy s bundlingem

Když Wrangler sestavuje váš Worker do balíčku, může se mu nepodařit vyřešit závislosti. Jednoduchým způsobem, jak problém vyřešit, je nastavit pro tyto závislosti alias.

Před tímto krokem ale ověřte, že je balíček ve vašem projektu správně nainstalován, ať už jako přímá závislost v package.json nebo jako tranzitivní závislost.

Pokud je alias správným řešením vašeho problému se závislostmi, máte několik možností:

Příklad: aliasing závislostí z NPM

Pomocí aliasování modulů můžete poskytnout implementaci balíčku NPM, který na Workers nefunguje, a to i v případě, že na tomto balíčku NPM závisíte pouze nepřímo, jako na závislosti jedné ze závislostí svého Workeru.

Některé balíčky NPM například závisí na node-fetch ↗, balíček, který poskytoval polyfill fetch() API, než bylo zabudováno do Node.js.

node-fetch není ve Workers potřeba, protože fetch() API poskytuje prostředí Workers runtime. A node-fetch nefunguje ve Workers, protože se spoléhá na v současnosti nepodporovaná Node.js API z http/https moduly.

Můžete vytvořit alias pro všechny importy node-fetch a místo toho odkazovat přímo na fetch() API, které je součástí prostředí Workers runtime:

{
	"alias": {
		"node-fetch": "./fetch-polyfill",
	},
}
[alias]
node-fetch = "./fetch-polyfill"
./fetch-polyfill
export default fetch;

Příklad: aliasing Node.js API

Pomocí aliasování modulů můžete poskytnout vlastní polyfill implementaci Node.js API, které v runtime Workers ještě není dostupné.

Řekněme například, že balíček NPM, na kterém závisíte, volá fs.readFile ↗. Modul fs můžete aliasovat přidáním následujícího do konfiguračního souboru Wrangler vašeho Workeru:

{
	"alias": {
		"fs": "./fs-polyfill",
	},
}
[alias]
fs = "./fs-polyfill"
./fs-polyfill
export function readFile() {
	// ...
}

V mnoha případech vám to umožní poskytnout jen tolik API, kolik je potřeba k tomu, aby závislost fungovala. Více o podpoře Node.js API v Cloudflare Workers se dozvíte na dokumentační stránka Cloudflare Workers Node.js API.

Zdrojové mapy

Zdrojové mapy převádět zkompilovaný a minifikovaný kód zpět na původní kód, který jste napsali. Source maps se kombinují se stack trace, který vrátí JavaScript runtime, aby vám zobrazily stack trace.

Příklad:

{
	"upload_source_maps": true,
}
upload_source_maps = true

Workers Sites

Workers Sites umožňuje hostovat statické weby nebo dynamické weby postavené na frameworcích jako Vue nebo React na Workers.

Příklad:

{
	"site": {
		"bucket": "./public",
		"include": ["upload_dir"],
		"exclude": ["ignore_dir"],
	},
}
[site]
bucket = "./public"
include = [ "upload_dir" ]
exclude = [ "ignore_dir" ]

Podpora proxy

Firemní sítě mívají ve svém provozu proxy servery, což může někdy způsobit problémy s připojením. Chcete-li nakonfigurovat Wrangler s příslušnými údaji o proxy, přidejte následující proměnné prostředí:

Chcete-li to nakonfigurovat na macOS, přidejte HTTP_PROXY=http://<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT> před vašimi příkazy Wrangler.

Příklad:

$ HTTP_PROXY=http://localhost:8080 wrangler dev

Pokud vaše IT oddělení nakonfigurovalo nastavení proxy na vašem počítači, mějte na paměti, že Wrangler při odchozích požadavcích použije první neprázdnou proměnnou prostředí z tohoto seznamu.

Pokud například oba https_proxy a http_proxy jsou nastaveny, Wrangler použije pouze https_proxy pro odchozí požadavky.

Zdroj pravdy

Doporučujeme považovat konfigurační soubor Wrangler za zdroj pravdy pro konfiguraci vašeho Workeru a pokud používáte Wrangler, neprovádět změny Workeru přes Cloudflare dashboard.

Pokud potřebujete provádět změny Workeru z dashboardu Cloudflare, dashboard vygeneruje úryvek TOML, který zkopírujete do konfiguračního souboru Wrangler. Díky tomu bude konfigurační soubor Wrangler vždy aktuální.

Pokud změníte proměnné prostředí v dashboardu Cloudflare, Wrangler je při dalším nasazení přepíše. Pokud chcete toto chování vypnout, přidejte keep_vars = true do konfiguračního souboru Wrangler.

Pokud změníte routes v dashboardu, Wrangler je při dalším nasazení přepíše routes nastavenými v konfiguračním souboru Wrangler. Pokud chcete routes spravovat pouze přes dashboard Cloudflare, odeberte z konfiguračního souboru Wrangler klíče route a routes. Poté přidejte workers_dev = false do konfiguračního souboru Wrangler. Další informace naleznete v Zastaralé funkce.

Wrangler vaše secrets (šifrované proměnné prostředí) nesmaže, pokud nespustíte wrangler secret delete <key>.

Vygenerovaná konfigurace Wrangler

Některé nástroje frameworků nebo vlastní procesy před sestavením vygenerují upravenou konfiguraci Wrangler, která se použije k nasazení kódu Workeru. V takovém případě může nástroj vytvořit i speciální .wrangler/deploy/config.json soubor, který Wranglera přesměruje na použití vygenerované konfigurace namísto původní, uživatelské konfigurace.

Wrangler používá tuto vygenerovanou konfiguraci pouze pro následující příkazy související s nasazením a vývojem:

Při spuštění těchto příkazů Wrangler prohledává strom adresářů od aktuálního pracovního adresáře a hledá soubor na cestě .wrangler/deploy/config.json. Tento soubor smí obsahovat pouze jediný objekt JSON ve tvaru:

{ "configPath": "../../path/to/wrangler.jsonc" }

Když tento config.json soubor existuje, Wrangler bude postupovat podle configPath (vzhledem k .wrangler/deploy/config.json soubor) a najde vygenerovaný konfigurační soubor Wrangleru, který se má načíst a použít v aktuálním příkazu. Wrangler uživateli zobrazí zprávu informující o tom, že konfigurace byla přesměrována do jiného souboru, než je uživatelův konfigurační soubor.

Vygenerovaný konfigurační soubor by neměl obsahovat žádné prostředí. Je to proto, že takový soubor by se v případě potřeby měl vytvářet jako součást kroku sestavení, který by už měl cílit na konkrétní prostředí. Tyto nástroje pro sestavení by měly pro jednotlivá prostředí generovat samostatné konfigurační soubory nasazení.

Příklad vlastního build nástroje

Běžným příkladem použití přesměrované konfigurace je situace, kdy vlastní build nástroj nebo framework potřebuje upravit uživatelskou konfiguraci použitou při nasazení, a to vygenerováním nové konfigurace v dist adresář.

Vygenerovaný dist/wrangler.jsonc může obsahovat:

{
	"name": "my-worker",
	"main": "./index.js",
	"vars": {
		"MY_VARIABLE": "staging variable"
	}
}

Nyní main vlastnost odkazuje na vstupní bod vygenerovaného kódu, není definováno žádné prostředí, a MY_VARIABLE proměnná se přeloží na hodnotu prostředí staging.

A .wrangler/deploy/config.json obsahuje cestu k vygenerovanému konfiguračnímu souboru:

{
	"configPath": "../../dist/wrangler.jsonc"
}