INTEGRITY Документация

← Cloudflare Workers / workers / wrangler

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

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

Рекомендуется относиться к файлу конфигурации Wrangler как к источник достоверных данных для настройки Worker.

Пример конфигурации 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>"

Окружения

Для Worker можно определить разные конфигурации с помощью Wrangler окружения. Существует среда по умолчанию (верхнего уровня), а также можно создавать именованные среды с собственной конфигурацией.

Они определяются в разделе [env.<name>] ключи, такие как [env.staging] который затем можно просмотреть или развернуть с помощью -e / --env флаг в wrangler команды, такие как npx wrangler deploy --env staging.

Большинство ключей являются наследуемыми: это означает, что конфигурацию верхнего уровня можно использовать в окружениях. Bindings, например vars или kv_namespaces, не наследуются и должны быть заданы явно.

Кроме того, есть несколько ключей, которые могут только отображаются на верхнем уровне.

Автоматическое предоставление ресурсов

Бета

При развёртывании Worker Wrangler может автоматически создавать необходимые ресурсы, так что заранее создавать их вручную не нужно.

На данный момент это работает для следующих ресурсов: KV, R2, D1, Flagship, AI Search, Agent Memory, Dispatch Namespaces и Queues.

Чтобы использовать эту функцию, добавьте привязки в файл конфигурации без добавляя идентификаторы ресурсов, а для R2 указывается имя bucket. Ресурсы будут созданы с именем вашего worker в качестве префикса.

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

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

Если вы развертываете worker с ресурсами без идентификаторов ресурсов из дашборда (например, через GitHub), ресурсы будут созданы, но их идентификаторы будут доступны только через дашборд. В настоящее время эти идентификаторы ресурсов не записываются обратно в ваш репозиторий.

Ключи только верхнего уровня

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

Наследуемые ключи

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

Ненаследуемые ключи

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

Типы маршрутов

Существует три типа маршруты: Custom Domains, маршруты, а также workers.dev.

Custom Domains

Custom Domains позволяют подключить Worker к домену или поддомену без изменения настроек DNS и без управления сертификатами.

Пример:

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

Маршруты

Маршруты позволяют сопоставить шаблон URL с Worker. Маршрут можно настроить как маршрут по zone ID, маршрут по zone name или простой маршрут.

Маршрут Zone ID

Пример:

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

Маршрут по имени зоны

Пример:

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

Простой маршрут

Это простой маршрут, для которого требуется только шаблон.

Пример:

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

workers.dev

Учётные записи Cloudflare Workers включают workers.dev поддомен, который можно настроить в Cloudflare dashboard.

{
	"workers_dev": false,
}
workers_dev = false

Триггеры

Триггеры позволяют определить cron выражение для вызова вашего Worker scheduled функция. См. Поддерживаемые cron-выражения.

Пример:

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

Observability

Observability настройка позволяет автоматически принимать, хранить, фильтровать и анализировать данные журналов, поступающие от Cloudflare Workers, прямо на панели управления вашего Cloudflare Worker.

Пример:

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

Пользовательские сборки

Можно настроить собственный шаг сборки, который будет выполняться перед развёртыванием Worker. См. Пользовательские сборки.

Пример:

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

Лимиты

На поведение Worker во время выполнения можно наложить ограничения. Ограничения поддерживаются только для Стандартная модель использования. Ограничения применяются только при развёртывании в сети Cloudflare, а не при локальной разработке. Лимит CPU можно задать на уровне не более 300,000 миллисекунд (5 минут).

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


Пример:

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

Bindings

Browser Run

API запуска Workers в браузере позволяет разработчикам программно управлять экземпляром headless браузера и взаимодействовать с ним, а также создавать сценарии автоматизации для своих приложений и продуктов.

A привязка browser предоставит вашему Worker аутентифицированную конечную точку для взаимодействия с выделенным экземпляром браузера Chromium.

Пример:

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

Базы данных D1

D1 это бессерверная SQL-база данных Cloudflare. Worker может выполнять запросы к базе данных D1 (или нескольким базам данных), создав привязка к каждой базе данных для D1 Workers Binding API.

Чтобы привязать базы данных D1 к Worker, присвойте массив из указанного ниже объекта [[d1_databases]] ключ.

Пример:

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

Привязки пространств имён диспетчеризации (Workers for Platforms)

Привязки пространств имён диспетчеризации обеспечивают связь между Worker динамической диспетчеризации и пространство имён диспетчеризации. Привязки dispatch namespace используются в Workers for Platforms. Workers for Platforms помогает программно развёртывать бессерверные функции от имени ваших клиентов.

{
	"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 обеспечивают низкую задержку координации и согласованное хранение для платформы Workers.

Чтобы привязать Durable Objects к Worker, присвойте массив из указанного ниже объекта durable_objects.bindings ключ.

Пример:

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

Экспорты

exports поле объявляет классы Durable Object, которые экспортирует этот Worker, и их состояние жизненного цикла. См. Экспорт классов Durable Object.

Каждая запись в exports индексируется по имени класса Durable Object. Поля каждой записи:

Пример:

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

Миграции

При внесении изменений в классы Durable Object в Worker, использующем устаревший migrations массив, необходимо выполнить миграцию. См. Миграции классов Durable Object (устаревший способ).

Пример:

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

Email bindings

Из Worker можно отправить письмо о его активности на адрес электронной почты, подтверждённый в Email Routing. Это полезно, например, когда вам нужно знать о срабатывании определённых типов событий.

Прежде чем привязать адрес электронной почты к своему Worker, необходимо включить Email Routing и иметь хотя бы один подтверждённый адрес электронной почты. Затем присвойте объекту (send_email) массив с нужным типом привязки электронной почты.

В файл Wrangler можно добавить один или несколько типов привязок. При этом каждый атрибут должен располагаться на отдельной строке:

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

Переменные окружения

Переменные окружения представляют собой тип привязки, который позволяет вам прикреплять текстовые строки или значения JSON к вашему Worker.

Пример:

{
	"$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 привязки позволяют взаимодействовать с любой базой данных Postgres и выполнять к ней запросы прямо из Worker.

Пример:

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

Изображения

Cloudflare Images позволяет отправлять запросы на преобразование, чтобы оптимизировать, изменять размер и обрабатывать изображения, хранящиеся во внешних источниках.

Чтобы привязать Images к Worker, присвойте массив из указанного ниже объекта images ключ.

binding (обязательно). Имя привязки, используемой для обращения к Images API.

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

Пространства имён KV

Workers KV представляет собой глобальное хранилище данных типа «ключ-значение» с низкой задержкой. Данные хранятся в небольшом числе централизованных дата-центров, а после обращения кешируются в дата-центрах Cloudflare.

Чтобы привязать пространства имен KV к Worker, присвойте массив из указанного ниже объекта kv_namespaces ключ.

Пример:

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

Пространства имён AI Search

AI Search это управляемый сервис поиска Cloudflare. пространство имён представляет собой логическую группировку экземпляров AI Search. Привязка (binding) предоставляет полный доступ ко всем экземплярам в пределах пространства имён.

Чтобы привязать пространства имен AI Search к Worker, присвойте массив из указанного ниже объекта ai_search_namespaces ключ.

Пример:

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

Инстансы AI Search

Чтобы привязаться напрямую к уже существующему AI Search экземпляр в пространство имён по умолчанию, присвойте массив приведённого ниже объекта для ai_search ключ. Эта привязка не поддерживает операции на уровне пространства имён, такие как list(), create(), или delete().

Пример:

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

Queues

Queues это глобальный сервис очередей сообщений Cloudflare, который предоставляет гарантированная доставка и групповая обработка сообщений. Чтобы взаимодействовать с очередью через Workers, вам нужен Worker-производитель для отправки сообщений в очередь и Worker-потребитель для извлечения пакетов сообщений из Queue. Один Worker может как отправлять сообщения, так и получать их из нескольких Queues.

Чтобы привязать Queues к Worker-отправителю, присвойте массив из указанного ниже объекта [[queues.producers]] ключ.

Пример:

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

Чтобы привязать Queues к Worker-получателю, присвойте массив из указанного ниже объекта [[queues.consumers]] ключ.

Пример:

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

Cloudflare R2 Storage позволяет разработчикам хранить большие объемы неструктурированных данных без высокой платы за исходящий трафик, характерной для обычных облачных хранилищ.

Чтобы привязать бакеты R2 к Worker, присвойте массив из указанного ниже объекта r2_buckets ключ.

Пример:

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

A Индекс Vectorize позволяет добавлять векторные эмбеддинги и выполнять по ним запросы для семантического поиска, классификации и других сценариев векторного поиска.

Чтобы привязать индексы Vectorize к Worker, присвойте массив из указанного ниже объекта vectorize ключ.

Пример:

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

Service bindings

Service binding позволяет отправлять HTTP-запросы другому Worker, минуя интернет. Запрос сразу вызывает целевой Worker, что снижает задержку по сравнению с запросом к стороннему сервису. См. О Service Bindings.

Чтобы привязать другие Workers к вашему Worker, присвойте массив из указанного ниже объекта services ключ.

Пример:

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

Static Assets

См. Assets.

Analytics Engine Datasets

Workers Analytics Engine предоставляет аналитику, наблюдаемость и журналирование данных из Workers. Записывайте точки данных в привязку вашего Worker, а затем запрашивайте данные с помощью SQL API.

Чтобы привязать наборы данных Analytics Engine к Worker, присвойте массив из указанного ниже объекта analytics_engine_datasets ключ.

Пример:

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

mTLS Certificates

Чтобы обмениваться данными с источниками, которым требуется аутентификация клиента, Worker может предъявлять сертификат mTLS в подзапросах. Wrangler предоставляет mtls-certificate команда для загрузки этих сертификатов и управления ими.

Чтобы создать привязка к сертификату mTLS для вашего Worker, присвойте массив объектов следующей структуры полю mtls_certificates ключ.

Пример конфигурационного файла Wrangler с привязкой сертификата 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>"

Привязки сертификатов mTLS затем можно использовать во время выполнения для обращения к защищённым источникам через их fetch метод.

Workers AI

Workers AI позволяет запускать модели машинного обучения в сети Cloudflare прямо из вашего кода: из Workers, Pages или откуда угодно через REST API.

В отличие от других bindings, для проекта Worker можно использовать только один AI binding.

Пример:

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

Workflows

Workflows позволяют создавать надежные многошаговые приложения на платформе Workers. Привязка Workflow дает вашему Worker возможность программно создавать экземпляры Workflow и управлять ими.

Чтобы привязать Workflows к Worker, присвойте массив из указанного ниже объекта workflows ключ.

Пример:

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

Assets

Static Assets позволяет разработчикам запускать front-end сайты на Workers. Можно настроить каталог ресурсов (assets), необязательную привязку runtime и параметры маршрутизации.

Для каждого Worker можно настроить только одну коллекцию ресурсов.

Следующие параметры доступны в разделе assets ключ.

Пример:

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

Также можно настроить run_worker_first с массивом шаблонов маршрутов:

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

Можно определить Containers для запуска рядом с вашим Worker с помощью containers поле.

Доступны следующие параметры:

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

Пользовательские типы инстансов

Вместо именованные типы экземпляров, вы можете задать пользовательский тип инстанса, отдельно настроив vCPU, память и диск. См. документация по лимитам об ограничениях для пользовательских типов инстансов.

Доступны следующие параметры:

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

Настройка SSH-доступа к экземпляру Container через Wrangler. Руководство по подключению к Containers по SSH см. в SSH.

Доступны следующие параметры:

Авторизованные ключи

Авторизованный ключ представляет собой открытый ключ, который можно использовать для подключения к Container по SSH.

Ниже перечислены свойства ключа:

Bundling

Wrangler может работать в двух режимах: режим сборки по умолчанию и --no-bundle режиме. В режиме бандлинга Wrangler обходит все импорты вашего кода и создаёт единый JavaScript-файл «entry-point». Импортированный исходный код «встраивается» в этот entry-point файл.

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

Пример:

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

Импорт модулей внутри Worker

Эти модули можно импортировать и использовать в Worker следующим образом:

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

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

Найдите дополнительные модули

По умолчанию Wrangler включает только те дополнительные модули, которые статически импортированы в исходном коде, как в примере выше. Если задать find_additional_modules к true в вашем конфигурационном файле, Wrangler будет обходить дерево файлов ниже base_dir. Любые файлы, соответствующие rules также будут включены в развёрнутый Worker как внешние модули без объединения в сборку. base_dir по умолчанию использует каталог, содержащий ваш main точка входа.

См. https://developers.cloudflare.com/workers/wrangler/bundling/ ↗ с подробностями и примерами.

Python Workers

По умолчанию Python Workers включает в бандл файлы и папки в python_modules в корне вашего Worker (рядом с конфигурационным файлом wrangler). Файлы в этом каталоге представляют собой добавленные через vendoring пакеты, и именно сюда инструмент pywrangler копирует пакеты. В некоторых случаях вы можете обнаружить, что файлы в этой папке слишком велики, и если ваш worker не использует их, они лишь увеличивают размер бандла без всякой необходимости.

Чтобы это исправить, можно исключить определенные файлы из сборки. Для этого используйте python_modules.excludes параметр, например:

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

Это исключит все файлы .pyc и __pycache__ каталоги внутри любого подкаталога в python_modules.

По умолчанию python_modules.excludes имеет значение ["**/*.pyc"], поэтому обязательно указывайте его при установке другого значения.

Настройки локальной разработки

Можно настроить различные аспекты локальной разработки, например локальный протокол или порт.

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

Секреты

Секреты являются типом binding, который позволяет прикрепление зашифрованных текстовых значений в ваш Worker.

secrets свойство конфигурации

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

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

Генерация типов

Когда secrets задан на любом уровне конфигурации, wrangler types генерирует типизированные привязки на основе имён, перечисленных в secrets.required и больше не определяет имена секретов на основе .dev.vars или .env файлы. Это позволяет запускать генерацию типов в окружениях, где эти файлы отсутствуют.

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

Развернуть

Когда secrets задан, wrangler deploy и wrangler versions upload проверьте, что все секреты в secrets.required настроены в Worker, прежде чем операция завершится успешно. Если каких-либо обязательных secrets не хватает, команда завершается ошибкой со списком secrets, которые нужно задать.

Локальная разработка

Разместите секреты для использования при локальной разработке либо в .dev.vars файл или .env файл, в том же каталоге, что и файл конфигурации Wrangler.

Эти файлы должны быть отформатированы с помощью dotenv ↗ синтаксис. Например:

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

Чтобы задать разные секреты для каждого окружения Cloudflare, создайте файлы с именами .dev.vars.<environment-name> или .env.<environment-name>.

Когда вы выбираете окружение Cloudflare в локальной разработке, соответствующий файл конкретного окружения загружается раньше общего .dev.vars (или .env) файл.

Псевдонимы модулей

Wrangler можно настроить так, чтобы все обращения к импорту определённого пакета заменялись выбранным вами модулем, задав alias поле:

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

При такой конфигурации любые вызовы import или require() модуль foo будет иметь псевдоним, указывающий на ваш модуль замены:

import { bar } from "foo";

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

Проблемы с Bundling

При сборке Worker с помощью Wrangler разрешение зависимостей иногда завершается ошибкой. Простое решение этой проблемы: настроить алиас для таких зависимостей.

Однако прежде чем это делать, убедитесь, что пакет правильно установлен в вашем проекте: либо как прямая зависимость в package.json или как транзитивная зависимость.

Если алиас является подходящим решением проблемы с зависимостью, у вас есть несколько вариантов:

Пример: алиасы для зависимостей из NPM

С помощью module aliasing можно предоставить реализацию NPM-пакета, который не работает в Workers, даже если вы используете этот NPM-пакет лишь косвенно, как зависимость одной из зависимостей вашего Worker.

Например, некоторые пакеты NPM зависят от node-fetch ↗, пакет, который предоставлял полифилл (polyfill) для fetch() API, до того как это было встроено в Node.js.

node-fetch не нужен в Workers, поскольку fetch() API предоставляется средой выполнения Workers. А node-fetch не работает в Workers, поскольку зависит от пока не поддерживаемых Node.js API из http/https модулей.

Можно задать псевдоним для всех импортов node-fetch чтобы вместо этого указывать напрямую на fetch() API, встроенный в среду выполнения Workers:

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

Пример: алиасы для API Node.js

С помощью module aliasing можно предоставить собственную реализацию полифилла для API Node.js, который пока недоступен в Workers runtime.

Например, предположим, что используемый вами пакет NPM вызывает fs.readFile ↗. Вы можете задать псевдоним для модуля fs, добавив следующее в файл конфигурации Wrangler вашего Worker:

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

Во многих случаях это позволяет реализовать ровно ту часть API, которой достаточно для работы зависимости. Подробнее о поддержке Node.js API в Cloudflare Workers можно узнать на Страница документации по Node.js API Cloudflare Workers.

Source maps

Source maps преобразовывать скомпилированный и минифицированный код обратно в исходный код, который вы написали. Source map объединяются со стеком вызовов, возвращаемым средой выполнения JavaScript, чтобы показать вам стек вызовов.

Пример:

{
	"upload_source_maps": true,
}
upload_source_maps = true

Workers Sites

Workers Sites позволяет размещать на Workers статические сайты, а также динамические сайты на фреймворках вроде Vue или React.

Пример:

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

Поддержка прокси

В корпоративных сетях часто используются прокси-серверы, что иногда приводит к проблемам с подключением. Чтобы настроить Wrangler с нужными параметрами прокси, добавьте следующие переменные окружения:

Чтобы настроить это в macOS, добавьте HTTP_PROXY=http://<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT> перед командами Wrangler.

Пример:

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

Если ваш IT-отдел настроил параметры прокси на вашем компьютере, учтите, что при исходящих запросах Wrangler будет использовать первую непустую переменную окружения из этого списка.

Например, если оба https_proxy и http_proxy заданы, Wrangler будет использовать только https_proxy для исходящих запросов.

Источник истины

Мы рекомендуем считать файл конфигурации Wrangler основным источником данных о конфигурации Worker и не вносить изменения в Worker через панель управления Cloudflare, если вы используете Wrangler.

Если вы вносите изменения в Worker через дашборд Cloudflare, дашборд создаст фрагмент TOML, который нужно скопировать в файл конфигурации Wrangler. Это поможет сохранять файл конфигурации Wrangler всегда актуальным.

Если вы измените переменные окружения в дашборде Cloudflare, при следующем развертывании Wrangler перезапишет их. Чтобы отключить такое поведение, добавьте keep_vars = true в файл конфигурации Wrangler.

Если вы измените маршруты в дашборде, при следующем развертывании Wrangler заменит их маршрутами, заданными в конфигурационном файле Wrangler. Чтобы управлять маршрутами только через дашборд Cloudflare, удалите ключи route и routes из конфигурационного файла Wrangler. Затем добавьте workers_dev = false в файл конфигурации Wrangler. Дополнительные сведения см. в Устаревшие функции.

Wrangler не удалит ваши секреты (зашифрованные переменные окружения), если вы не выполните wrangler secret delete <key>.

Сгенерированная конфигурация Wrangler

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

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

При выполнении этих команд Wrangler ищет вверх по дереву каталогов от текущего рабочего каталога файл по пути .wrangler/deploy/config.json. Этот файл должен содержать только один JSON объект следующего вида:

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

Когда этот config.json файл существует, Wrangler будет следовать configPath (относительно .wrangler/deploy/config.json файл), чтобы найти сгенерированный файл конфигурации Wrangler для загрузки и использования в текущей команде. Wrangler выведет сообщение пользователю о том, что конфигурация была перенаправлена в файл, отличный от пользовательского файла конфигурации.

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

Пример пользовательского инструмента сборки

Типичный пример использования перенаправленной конфигурации: пользовательский инструмент сборки или фреймворк хочет изменить конфигурацию пользователя, применяемую при развертывании, создавая новую конфигурацию в dist каталог.

Сгенерированный dist/wrangler.jsonc может содержать:

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

Теперь main свойство указывает на точку входа сгенерированного кода, окружение не определено, а MY_VARIABLE переменная разрешается в значение окружения staging.

И .wrangler/deploy/config.json содержит путь к сгенерированному файлу конфигурации:

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