INTEGRITY Dokumentace

← Cloudflare Workers / workers / wrangler / migration / v1-to-v2 / wrangler-legacy

Konfigurace

Kontext

Než budete moci Worker publikovat, bude váš projekt vyžadovat určitou konfiguraci. Ta se provádí úpravou klíčů a hodnot uložených v souboru Wrangler, který se nachází v kořenovém adresáři projektu. Tento soubor musíte před publikováním ručně upravit, abyste změnili příslušné klíče a hodnoty.

Prostředí

Konfigurace nejvyšší úrovně je soubor hodnot, které zadáte v horní části souboru Wrangler. Tyto hodnoty dědí všechna prostředí, pokud v daném prostředí nejsou definovány jinak.

Struktura konfigurace nejvyšší úrovně v konfiguračním souboru Wrangler vypadá takto:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "your-worker",
	"type": "javascript",
	"account_id": "your-account-id",
	// This field specifies that the Worker
	// will be deployed to a *.workers.dev domain
	"workers_dev": true,
	// -- OR --
	// These fields specify that the Worker
	// will deploy to a custom domain
	"zone_id": "your-zone-id",
	"routes": [
		"example.com/*"
	]
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "your-worker"
type = "javascript"
account_id = "your-account-id"
workers_dev = true
zone_id = "your-zone-id"
routes = [ "example.com/*" ]

Konfigurace prostředí (volitelné): konfigurační hodnoty, které zadáte pod [env.name] ve vašem souboru Wrangler.

Prostředí umožňují nasadit stejný projekt na více míst pod více názvy. Tato prostředí se používají s --env nebo -e příznak na příkazy které nasazují živé Workers:

Některé vlastnosti prostředí lze zděděný z konfigurace nejvyšší úrovně, ale pokud jsou v prostředí nastaveny nové hodnoty, vždy přepíší hodnoty na nejvyšší úrovni.

Příklad [env.name] konfigurace vypadá takto:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"type": "javascript",
	"name": "your-worker",
	"account_id": "your-account-id",
	"vars": {
		"FOO": "default FOO value",
		"BAR": "default BAR value"
	},
	"kv_namespaces": [
		{
			"binding": "FOO",
			"id": "1a...",
			"preview_id": "1b..."
		}
	],
	"env": {
		"helloworld": {
			// Now adding configuration keys for the "helloworld" environment.
			// These new values will override the top-level configuration.
			"name": "your-worker-helloworld",
			"account_id": "your-other-account-id",
			"vars": {
				"FOO": "env-helloworld FOO value",
				"BAR": "env-helloworld BAR value"
			},
			"kv_namespaces": [
				{
					// Redeclare kv namespace bindings for each environment
					// NOTE: In this case, passing new IDs because new `account_id` value.
					"binding": "FOO",
					"id": "888...",
					"preview_id": "999..."
				}
			]
		}
	}
}
"$schema" = "./node_modules/wrangler/config-schema.json"
type = "javascript"
name = "your-worker"
account_id = "your-account-id"

[vars]
FOO = "default FOO value"
BAR = "default BAR value"

[[kv_namespaces]]
binding = "FOO"
id = "1a..."
preview_id = "1b..."

[env.helloworld]
name = "your-worker-helloworld"
account_id = "your-other-account-id"

  [env.helloworld.vars]
  FOO = "env-helloworld FOO value"
  BAR = "env-helloworld BAR value"

  [[env.helloworld.kv_namespaces]]
  binding = "FOO"
  id = "888..."
  preview_id = "999..."

Chcete-li nasadit tento ukázkový Worker do helloworld prostředí byste spustili wrangler deploy --env helloworld.

Klíče

V souboru Wrangler existují tři typy klíčů:

vars

vars klíč definuje tabulku proměnné prostředí poskytnuté vašemu Worker skriptu. Všechny hodnoty jsou ve formátu prostého textu.

Použití:

{
	"vars": {
		"FOO": "some value",
		"BAR": "some other string"
	}
}
[vars]
FOO = "some value"
BAR = "some other string"

Klíče tabulky jsou ve vašem Workeru dostupné jako globální proměnné, které obsahují přiřazené hodnoty.

// Worker code:
console.log(FOO);
//=> "some value"

console.log(BAR);
//=> "some other string"

Alternativně můžete definovat vars ve formátu vložené tabulky (inline table). Aby byla konfigurace TOML platná, nesmí tento styl obsahovat žádné nové řádky:

{
	"vars": {
		"FOO": "some value",
		"BAR": "some other string"
	}
}
[vars]
FOO = "some value"
BAR = "some other string"

kv_namespaces

kv_namespaces definuje seznam vazeb na KV namespace pro váš Worker.

Použití:

{
	"kv_namespaces": [
		{
			"binding": "FOO",
			"id": "0f2ac74b498b48028cb68387c421e279",
			"preview_id": "6a1ddb03f3ec250963f0a1e46820076f"
		},
		{
			"binding": "BAR",
			"id": "068c101e168d03c65bddf4ba75150fb0",
			"preview_id": "fb69528dbc7336525313f2e8c3b17db0"
		}
	]
}
[[kv_namespaces]]
binding = "FOO"
id = "0f2ac74b498b48028cb68387c421e279"
preview_id = "6a1ddb03f3ec250963f0a1e46820076f"

[[kv_namespaces]]
binding = "BAR"
id = "068c101e168d03c65bddf4ba75150fb0"
preview_id = "fb69528dbc7336525313f2e8c3b17db0"

Alternativně můžete definovat kv namespaces takto:

{
	"kv_namespaces": [
		{
			"binding": "FOO",
			"preview_id": "abc456",
			"id": "abc123"
		},
		{
			"binding": "BAR",
			"preview_id": "xyz456",
			"id": "xyz123"
		}
	]
}
[[kv_namespaces]]
binding = "FOO"
preview_id = "abc456"
id = "abc123"

[[kv_namespaces]]
binding = "BAR"
preview_id = "xyz456"
id = "xyz123"

Podobně jako proměnné prostředí a secrets, binding názvy jsou ve vašem Workeru dostupné jako globální proměnné.

// Worker script:

let value = await FOO.get("keyname");
//=> gets the value for "keyname" from
//=> the FOO variable, which points to
//=> the "0f2ac...e279" KV namespace

web

A Workers Site vygenerovaný pomocí wrangler generate --site nebo wrangler init --site.

Použití:

{
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site"
	}
}
[site]
bucket = "./public"
entry-point = "workers-site"

Můžete si také definovat svůj site pomocí alternativní syntaxe TOML ↗.

Limity úložiště

Pro výjimečně velké stránky nemusí být Workers Sites ideální volbou. Platí limit 25 MiB na stránku nebo soubor. Wrangler navíc pro vaše soubory vytvoří manifest prostředků, který se započítává do limitu velikosti vašeho skriptu. Pokud máte příliš mnoho souborů, Workers Sites možná nebudete moci použít.

Výhradní zahrnování souborů/adresářů

Pokud chcete zahrnout jen určitou sadu souborů nebo adresářů ve svém bucket, přidejte include pole do svého [site] sekci vašeho souboru Wrangler:

{
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site",
		"include": [ // must be an array.
			"included_dir"
		]
	}
}
[site]
bucket = "./public"
entry-point = "workers-site"
include = [ "included_dir" ]

Wrangler nahraje pouze soubory nebo adresáře odpovídající vzorům v include pole.

Vylučování souborů/adresářů

Pokud chcete vyloučit soubory nebo adresáře ve svém bucket, přidejte exclude pole do svého [site] sekci vašeho souboru Wrangler:

{
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site",
		"exclude": [ // must be an array.
			"excluded_dir"
		]
	}
}
[site]
bucket = "./public"
entry-point = "workers-site"
exclude = [ "excluded_dir" ]

Wrangler bude ignorovat soubory nebo adresáře odpovídající vzorům v exclude pole při nahrávání assetů do Workers KV.

Include > Exclude

Pokud zadáte oba include a exclude pole, include pole se použije a exclude pole bude ignorováno.

Položky ignorované ve výchozím nastavení

Wrangler vždy ignoruje:

Více o vzorech include/exclude

Viz dokumentace ke gitignore ↗ kde se dozvíte více o standardních vzorech shody.

Přizpůsobení sestavení Sites

Projekty Workers Sites standardně používají webpack. Můžete však vlastní konfigurace webpacku, mějte na paměti svůj entry a context nastavení.

Můžete také použít [build] sekci s Workers Sites, pokud váš build krok vyřeší závislosti v node_modules. Přečtěte si vlastní sestavení sekci pro další informace.

triggery

Sada cron triggerů, které Worker volají podle plánu.

Použití:

{
	"triggers": {
		"crons": [
			"0 0 * JAN-JUN FRI",
			"0 0 LW JUL-DEC *"
		]
	}
}
[triggers]
crons = [ "0 0 * JAN-JUN FRI", "0 0 LW JUL-DEC *" ]

dev

Argumenty pro wrangler dev lze nastavit zde, abyste je nemuseli opakovaně zadávat.

Použití:

{
	"dev": {
		"port": 9000,
		"local_protocol": "https"
	}
}
[dev]
port = 9_000
local_protocol = "https"

sestavení

Vlastní build command pro váš projekt. Existují dvě konfigurace podle formátu vašeho Workeru: service-worker a modules.

Service Workers

Tato sekce se týká přizpůsobení Workers pomocí service-worker formát. Tito Workers používají addEventListener a vypadají následovně:

addEventListener("fetch", (event) => {
	event.respondWith(new Response("I'm a service Worker!"));
});

Použití:

{
	"build": {
		"command": "npm install && npm run build",
		"upload": {
			"format": "service-worker"
		}
	}
}
[build]
command = "npm install && npm run build"

  [build.upload]
  format = "service-worker"
[build]
[build.upload]

Moduly

Workers nyní podporují syntaxi ES Modules. Tento formát umožňuje exportovat kolekci souborů nebo modulů, na rozdíl od formátu Service Worker, který vyžaduje nahrání jediného souboru.

Moduly Workers export své obslužné rutiny událostí namísto použití addEventListener volání.

Moduly dostávají všechny vazby (KV Namespaces, Environment Variables a Secrets) jako argumenty exportovaných handlerů. Ve formátu Service Worker jsou tyto vazby dostupné jako globální proměnné.

Nahraný modul může import další nahrané ES moduly. Pokud používáte formát CommonJS, můžete require další nahrané moduly CommonJS.

import html from "./index.html";

export default {
	// * request is the same as `event.request` from the service worker format
	// * waitUntil() and passThroughOnException() are accessible from `ctx` instead of `event` from the service worker format
	// * env is where bindings like KV namespaces, Durable Object namespaces, Config variables, and Secrets
	// are exposed, instead of them being placed in global scope.
	async fetch(request, env, ctx) {
		const headers = { "Content-Type": "text/html;charset=UTF-8" };
		return new Response(html, { headers });
	},
};

Chcete-li vytvořit projekt Workers pomocí Wrangler a modulů, přidejte [build] sekce:

{
	"build": {
		"command": "npm install && npm run build",
		"upload": {
			"format": "modules",
			"main": "./worker.mjs"
		}
	}
}
[build]
command = "npm install && npm run build"

  [build.upload]
  format = "modules"
  main = "./worker.mjs"
[build]
[build.upload]

Výchozí hodnoty:

{
	// You do not need to include these default rules in your [Wrangler configuration file](/workers/wrangler/configuration/), they are implicit.
	// The default rules are treated as the last two rules in the list.
	"build": {
		"upload": {
			"format": "modules",
			"main": "./worker.mjs",
			"rules": [
				{
					"type": "ESModule",
					"globs": [
						"**/*.mjs"
					]
				},
				{
					"type": "CommonJS",
					"globs": [
						"**/*.js",
						"**/*.cjs"
					]
				}
			]
		}
	}
}
[build.upload]
format = "modules"
main = "./worker.mjs"

  [[build.upload.rules]]
  type = "ESModule"
  globs = [ "**/*.mjs" ]

  [[build.upload.rules]]
  type = "CommonJS"
  globs = [ "**/*.js", "**/*.cjs" ]

Příklad

Pro ilustraci, jak se tyto úrovně používají, uvádíme soubor Wrangler s více prostředími:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	// top level configuration
	"type": "javascript",
	"name": "my-worker-dev",
	"account_id": "12345678901234567890",
	"zone_id": "09876543210987654321",
	"route": "dev.example.com/*",
	"usage_model": "unbound",
	"kv_namespaces": [
		{
			"binding": "FOO",
			"id": "b941aabb520e61dcaaeaa64b4d8f8358",
			"preview_id": "03c8c8dd3b032b0528f6547d0e1a83f3"
		},
		{
			"binding": "BAR",
			"id": "90e6f6abd5b4f981c748c532844461ae",
			"preview_id": "e5011a026c5032c09af62c55ecc3f438"
		}
	],
	"build": {
		"command": "webpack",
		"upload": {
			"format": "service-worker"
		}
	},
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site"
	},
	"dev": {
		"ip": "0.0.0.0",
		"port": 9000,
		"local_protocol": "http",
		"upstream_protocol": "https"
	},
	"env": {
		// environment configuration
		"staging": {
			"name": "my-worker-staging",
			"route": "staging.example.com/*",
			"kv_namespaces": [
				{
					"binding": "FOO",
					"id": "0f2ac74b498b48028cb68387c421e279"
				},
				{
					"binding": "BAR",
					"id": "068c101e168d03c65bddf4ba75150fb0"
				}
			]
		},
		// environment configuration
		"production": {
			"workers_dev": true,
			"kv_namespaces": [
				{
					"binding": "FOO",
					"id": "0d2ac74b498b48028cb68387c421e233"
				},
				{
					"binding": "BAR",
					"id": "0d8c101e168d03c65bddf4ba75150f33"
				}
			]
		}
	}
}
"$schema" = "./node_modules/wrangler/config-schema.json"
type = "javascript"
name = "my-worker-dev"
account_id = "12345678901234567890"
zone_id = "09876543210987654321"
route = "dev.example.com/*"
usage_model = "unbound"

[[kv_namespaces]]
binding = "FOO"
id = "b941aabb520e61dcaaeaa64b4d8f8358"
preview_id = "03c8c8dd3b032b0528f6547d0e1a83f3"

[[kv_namespaces]]
binding = "BAR"
id = "90e6f6abd5b4f981c748c532844461ae"
preview_id = "e5011a026c5032c09af62c55ecc3f438"

[build]
command = "webpack"

  [build.upload]
  format = "service-worker"

[site]
bucket = "./public"
entry-point = "workers-site"

[dev]
ip = "0.0.0.0"
port = 9_000
local_protocol = "http"
upstream_protocol = "https"

[env.staging]
name = "my-worker-staging"
route = "staging.example.com/*"

  [[env.staging.kv_namespaces]]
  binding = "FOO"
  id = "0f2ac74b498b48028cb68387c421e279"

  [[env.staging.kv_namespaces]]
  binding = "BAR"
  id = "068c101e168d03c65bddf4ba75150fb0"

[env.production]
workers_dev = true

  [[env.production.kv_namespaces]]
  binding = "FOO"
  id = "0d2ac74b498b48028cb68387c421e233"

  [[env.production.kv_namespaces]]
  binding = "BAR"
  id = "0d8c101e168d03c65bddf4ba75150f33"