← Cloudflare Workers / workers / wrangler

Окружения

Wrangler позволяет использовать окружения для создания разных конфигураций одного и того же приложения Worker. Окружения настраиваются в конфигурационный файл Wrangler.

Создавая окружение, вы фактически создаёте в Cloudflare новый Worker с именем <top-level-name>-<environment-name>. Например, проект Worker с именем my-worker с окружением dev будет развёрнут как Worker с именем my-worker-dev.

Ознакомьтесь со следующей схемой работы с окружениями:

Создайте Worker с именем my-worker например.
Создайте окружение, например dev, в Worker конфигурационный файл Wrangler, добавив [env.<ENV_NAME>] раздел.
{ "name": "my-worker", "env": { "<ENV_NAME>": { // environment-specific configuration goes here } } }
name = "my-worker" [env] "<ENV_NAME>" = { }
Можно настроить dev окружение с другими значениями, отличными от окружения верхнего уровня. См. здесь о том, как разные параметры наследуются (или не наследуются) между окружениями. Например, чтобы задать другой маршрут для Worker в dev окружение:
{ "$schema": "./node_modules/wrangler/config-schema.json", "name": "your-worker", "route": "example.com", "env": { "dev": { "route": "dev.example.com", }, }, }
"$schema" = "./node_modules/wrangler/config-schema.json" name = "your-worker" route = "example.com" [env.dev] route = "dev.example.com"
Окружения используются с --env или -e флаг для команд Wrangler. Например, вы можете разрабатывать Worker в dev окружение, выполнив npx wrangler dev -e=dev, и разверните его с помощью npx wrangler deploy -e=dev.

Также вы можете использовать CLOUDFLARE_ENV переменная окружения чтобы выбрать активное окружение. Например, CLOUDFLARE_ENV=dev npx wrangler deploy развернёт в dev окружение. --env аргумент командной строки имеет приоритет над CLOUDFLARE_ENV переменную окружения.

Примечание
Примечание
Если вы используете Cloudflare Vite plugin, вы выбираете среду во время разработки или сборки с помощью CLOUDFLARE_ENV переменную окружения вместо --env флаг. В противном случае окружения определяются в файле конфигурации Worker, как обычно. Подробнее об использовании окружений с плагином Cloudflare для Vite см. в документация по плагину.

Ненаследуемые ключи и окружения

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

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

Ознакомьтесь со следующим примером файла Wrangler:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	"vars": {
		"API_HOST": "example.com",
	},
	"kv_namespaces": [
		{
			"binding": "<BINDING_NAME>",
			"id": "<KV_NAMESPACE_ID_DEV>",
		},
	],
	"env": {
		"production": {
			"vars": {
				"API_HOST": "production.example.com",
			},
			"kv_namespaces": [
				{
					"binding": "<BINDING_NAME>",
					"id": "<KV_NAMESPACE_ID_PRODUCTION>",
				},
			],
		},
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"

[vars]
API_HOST = "example.com"

[[kv_namespaces]]
binding = "<BINDING_NAME>"
id = "<KV_NAMESPACE_ID_DEV>"

[env.production.vars]
API_HOST = "production.example.com"

[[env.production.kv_namespaces]]
binding = "<BINDING_NAME>"
id = "<KV_NAMESPACE_ID_PRODUCTION>"

Service bindings

Чтобы использовать привязка к сервису который нацелен на Worker в определённом окружении, нужно добавить имя окружения к имени целевого Worker в service поле. Оно должно быть в формате <worker-name>-<environment-name>. В примере ниже показаны два Worker, у каждого из которых есть staging окружение. worker-b имеет Service Binding к worker-a. Обратите внимание, как service поле в staging окружение указывает на worker-a-staging, тогда как service binding верхнего уровня указывает на worker-a.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "worker-a",
	"vars": {
		"FOO": "<top-level-var>",
	},
	"env": {
		"staging": {
			"vars": {
				"FOO": "<staging-var>",
			},
		},
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "worker-a"

[vars]
FOO = "<top-level-var>"

[env.staging.vars]
FOO = "<staging-var>"

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "worker-b",
	"services": {
		"binding": "<BINDING_NAME>",
		"service": "worker-a",
	},
	// Note how `service = "worker-a-staging"`
	"env": {
		"staging": {
			"service": {
				"binding": "<BINDING_NAME>",
				"service": "worker-a-staging",
			},
		},
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "worker-b"

[services]
binding = "<BINDING_NAME>"
service = "worker-a"

[env.staging.service]
binding = "<BINDING_NAME>"
service = "worker-a-staging"

Секреты для продакшн-среды

Вы можете назначать специфичные для окружения секреты выполнив команду wrangler secret put <KEY> -env. Также можно создать dotenv файлы типов с именем .dev.vars.<environment-name>.

Подобно другим переменным окружения, секреты ненаследуемый и должны быть определены для каждого окружения.

Секреты при локальной разработке

Разместите секреты для использования при локальной разработке либо в .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) файл.

При использовании .dev.vars.<environment-name> файлов все секреты должны быть определены отдельно для каждого окружения. Если .dev.vars.<environment-name> существует, то будет загружен только он; .dev.vars файл не будет загружен.
В противоположность этому все соответствующие .env файлов, и их значения объединяются. Для каждой переменной используется значение из наиболее специфичного файла в следующем порядке приоритета:
- .env.<environment-name>.local (наиболее специфичный)
- .env.local
- .env.<environment-name>
- .env (наименее специфичный)

Управление обработкой `.env`

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

Чтобы отключить загрузку local dev vars из .env файлы без указания .dev.vars файле задайте CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV переменную окружения на "false".
Чтобы включить все переменные окружения, заданные в окружении процесса вашей системы, в качестве переменных локальной разработки, убедитесь, что отсутствует .dev.vars а затем задайте CLOUDFLARE_INCLUDE_PROCESS_ENV переменную окружения на "true". Это не требуется при использовании secrets свойство конфигурации, который загружается из process.env автоматически.

Примеры

Промежуточные и рабочие среды

Следующий файл Wrangler добавляет два окружения, [env.staging] и [env.production], в файл Wrangler. Если вы разворачиваете в Custom Domain или маршрут, вам нужно указать route или routes ключ для каждого окружения.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	"route": "dev.example.com/*",
	"vars": {
		"ENVIRONMENT": "dev",
	},
	"env": {
		"staging": {
			"vars": {
				"ENVIRONMENT": "staging",
			},
			"route": "staging.example.com/*",
		},
		"production": {
			"vars": {
				"ENVIRONMENT": "production",
			},
			"routes": ["example.com/foo/*", "example.com/bar/*"],
		},
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
route = "dev.example.com/*"

[vars]
ENVIRONMENT = "dev"

[env.staging]
route = "staging.example.com/*"

  [env.staging.vars]
  ENVIRONMENT = "staging"

[env.production]
routes = [ "example.com/foo/*", "example.com/bar/*" ]

  [env.production.vars]
  ENVIRONMENT = "production"

Имя окружения можно передать через --env флаг для выполнения команд в определённом окружении.

При такой конфигурации Wrangler будет вести себя следующим образом:

npx wrangler deploy

Uploaded my-worker
Published my-worker
  dev.example.com/*

npx wrangler deploy --env staging

Uploaded my-worker-staging
Published my-worker-staging
  staging.example.com/*

npx wrangler deploy --env production

Uploaded my-worker-production
Published my-worker-production
  example.com/*

Любой определённый переменные окружения ( vars ключ) доступны через env объект в вашем Worker.

При такой конфигурации env.ENVIRONMENT переменную можно использовать для вызова определенного кода в зависимости от заданного окружения:

export default {
	async fetch(request, env, ctx) {
		if (env.ENVIRONMENT === "staging") {
			// staging-specific code
		} else if (env.ENVIRONMENT === "production") {
			// production-specific code
		}
	},
};

Промежуточная среда с *.workers.dev

Чтобы развернуть код в вашем *.workers.dev поддомен, включите workers_dev = true в нужном окружении. Ваш файл Wrangler может выглядеть так:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	"route": "example.com/*",
	"env": {
		"staging": {
			"workers_dev": true,
		},
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
route = "example.com/*"

[env.staging]
workers_dev = true

При такой конфигурации Wrangler будет вести себя следующим образом:

npx wrangler deploy

Uploaded my-worker
Published my-worker
  example.com/*

npx wrangler deploy --env staging

Uploaded my-worker
Published my-worker
  https://my-worker-staging.<YOUR_SUBDOMAIN>.workers.dev