Документация Запланировать пилот

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

Конфигурация

Контекст

Перед публикацией Worker потребуется настроить проект. Настройка выполняется путём изменения ключей и значений в файле Wrangler, расположенном в корне каталога проекта. Перед публикацией вам нужно вручную отредактировать этот файл, чтобы изменить ключи и значения.

Окружения

Конфигурация верхнего уровня представляет собой набор значений, которые указываются в начале файла Wrangler. Эти значения наследуются всеми окружениями, если иное не задано непосредственно в окружении.

Ниже показана структура конфигурации верхнего уровня в файле Wrangler:

{
	"$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/*" ]

Конфигурация окружения (необязательно): значения конфигурации, которые вы указываете в разделе [env.name] в файле Wrangler.

Окружения позволяют развертывать один и тот же проект в нескольких местах под разными именами. Эти окружения используются с --env или -e флаг на команды которые разворачивают действующие Workers:

Некоторые свойства окружения можно унаследованный из конфигурации верхнего уровня, но если в окружении заданы новые значения, они всегда переопределяют значения верхнего уровня.

Пример [env.name] конфигурация выглядит так:

{
	"$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..."

Чтобы развернуть этот пример Worker в helloworld окружение, вы бы выполнили wrangler deploy --env helloworld.

Ключи

В файле Wrangler есть три типа ключей:

vars

vars ключ определяет таблицу переменные окружения предоставленные вашему скрипту Worker. Все значения являются открытым текстом.

Использование:

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

Ключи таблицы доступны вашему Worker в виде глобальных переменных, которые содержат соответствующие им значения.

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

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

Также вы можете определить vars с использованием формата inline table. В этом стиле не должно быть переносов строк, чтобы конфигурация TOML считалась допустимой:

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

kv_namespaces

kv_namespaces определяет список привязок пространств имен KV для вашего Worker.

Использование:

{
	"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"

Также вы можете определить kv namespaces следующим образом:

{
	"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"

Подобно переменным окружения и secrets, binding имена доступны вашему Worker в виде глобальных переменных.

// 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

сайт

A Workers Site сгенерированный с помощью wrangler generate --site или wrangler init --site.

Использование:

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

Также можно определить собственный site используя альтернативный синтаксис TOML ↗.

Лимиты хранилища

Для исключительно больших страниц Workers Sites может не подойти. Действует ограничение 25 МиБ на страницу или файл. Кроме того, Wrangler создаёт манифест ресурсов для ваших файлов, который учитывается в лимите размера скрипта. Если файлов слишком много, использовать Workers Sites может не получиться.

Включение только определённых файлов и каталогов

Если вы хотите включить только определённый набор файлов или каталогов в bucket, добавьте include поле в ваш [site] раздел вашего файла 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 будет загружать только файлы и каталоги, соответствующие шаблонам в include массив.

Исключение файлов и каталогов

Если вы хотите исключить файлы или каталоги в bucket, добавьте exclude поле в ваш [site] раздел вашего файла 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 будет игнорировать файлы и каталоги, соответствующие шаблонам в exclude массив при загрузке ресурсов в Workers KV.

Include > Exclude

Если вы укажете оба include и exclude поля, include поле будет использовано, а exclude поле будет проигнорировано.

Игнорируемые записи по умолчанию

Wrangler всегда игнорирует:

Подробнее о шаблонах include/exclude

См. документация по gitignore ↗ чтобы узнать больше о стандартных шаблонах сопоставления.

Настройка сборки Sites

По умолчанию проекты Workers Sites используют webpack. Однако вы можете использование собственной конфигурации webpack, учитывайте ваш entry и context настройки.

Вы также можете использовать [build] раздел с Workers Sites, при условии что на этапе сборки зависимости разрешаются в node_modules. См. пользовательские сборки раздел для получения дополнительной информации.

триггеры

Набор cron-триггеров, которые вызывают Worker по расписанию.

Использование:

{
	"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

Аргументы для wrangler dev можно настроить здесь, чтобы не передавать их каждый раз.

Использование:

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

сборка

Пользовательская команда сборки для вашего проекта. Существует две конфигурации в зависимости от формата вашего Worker: service-worker и modules.

Service Workers

Этот раздел посвящен настройке Workers с помощью service-worker формат. Такие Workers используют addEventListener и выглядеть следующим образом:

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

Использование:

{
	"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]

Модули

Теперь Workers поддерживает синтаксис ES Modules. Этот формат позволяет экспортировать набор файлов и/или модулей, в отличие от формата Service Worker, который требует загрузки одного файла.

Модульные Workers export свои обработчики событий вместо использования addEventListener вызовы.

Модули получают все привязки (KV Namespaces, Environment Variables и Secrets) в качестве аргументов экспортируемых обработчиков. В формате Service Worker эти привязки доступны как глобальные переменные.

Загруженный модуль может import другие загруженные ES-модули. При использовании формата CommonJS вы можете require другие загруженные модули 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 });
	},
};

Чтобы создать проект Workers с помощью Wrangler и Modules, добавьте [build] раздел:

{
	"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]

Значения по умолчанию:

{
	// 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" ]

Пример

Чтобы показать, как применяются эти уровни, вот файл Wrangler с несколькими средами:

{
	"$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"

Запросите бесплатный пилот

Запланировать пилот