← Cloudflare Workers / workers / vite-plugin / reference

Cloudflare Environments

Файл конфигурации Worker может содержать настройки для нескольких Окружения Cloudflare. С плагином Cloudflare для Vite среда Cloudflare выбирается на этапе разработки или сборки путём указания CLOUDFLARE_ENV переменной окружения. Рассмотрим следующий пример конфигурационного файла Worker:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"main": "./src/index.ts",
	"vars": {
		"MY_VAR": "Top-level var"
	},
	"env": {
		"staging": {
			"vars": {
				"MY_VAR": "Staging var"
			}
		},
		"production": {
			"vars": {
				"MY_VAR": "Production var"
			}
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"
main = "./src/index.ts"

[vars]
MY_VAR = "Top-level var"

[env.staging.vars]
MY_VAR = "Staging var"

[env.production.vars]
MY_VAR = "Production var"

Если вы выполните CLOUDFLARE_ENV=production vite build то вывод wrangler.json файл, созданный при сборке, будет представлять собой плоскую конфигурацию для окружения Cloudflare 'production', как показано в следующем примере:

{
	"name": "my-worker",
	"compatibility_date": "2025-04-03",
	"main": "index.js",
	"vars": { "MY_VAR": "Production var" }
}

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

Окружения Cloudflare также можно использовать при разработке. Например, вы можете выполнить CLOUDFLARE_ENV=development vite dev. Обычно среда верхнего уровня по умолчанию используется как среда разработки, а дополнительные среды добавляются по мере необходимости.

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

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

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 (наименее специфичный)

Вы можете сочетать концепции Окружения Cloudflare и Режимы Vite ↗. При таком подходе режим Vite можно использовать для выбора среды Cloudflare, а для определения конфигурации и кода конкретной среды можно использовать единый метод. Вернёмся к предыдущему примеру:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"main": "./src/index.ts",
	"vars": {
		"MY_VAR": "Top-level var"
	},
	"env": {
		"staging": {
			"vars": {
				"MY_VAR": "Staging var"
			}
		},
		"production": {
			"vars": {
				"MY_VAR": "Production var"
			}
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"
main = "./src/index.ts"

[vars]
MY_VAR = "Top-level var"

[env.staging.vars]
MY_VAR = "Staging var"

[env.production.vars]
MY_VAR = "Production var"

Затем укажите .env.staging и .env.production файлы:

CLOUDFLARE_ENV=staging

CLOUDFLARE_ENV=production

По умолчанию vite build использует режим Vite 'production'. Поэтому Vite загрузит .env.production файл, чтобы получить переменные окружения, используемые при сборке. Поскольку .env.production файл содержит CLOUDFLARE_ENV=production, плагин Cloudflare для Vite выберет окружение Cloudflare 'production'. Значение MY_VAR поэтому будет 'Production var'. Если вы выполните vite build --mode staging то будет использован режим Vite 'staging' и выбрано окружение Cloudflare 'staging'. Значение MY_VAR поэтому будет 'Staging var'.

Подробнее об использовании .env файлы с Vite, см. соответствующая документация ↗.