← Cloudflare Workers / workers / configuration

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

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

Строки и значения JSON не шифруются и полезны для хранения конфигурации приложения.

Чтобы добавить переменные окружения с помощью Wrangler, задайте текстовые и JSON значения через [vars] конфигурацию в файле Wrangler. В следующем примере API_HOST и API_ACCOUNT_ID являются текстовыми значениями, и SERVICE_X_DATA это значение JSON.

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

Пример того, как получить доступ к API_HOST переменную окружения в коде вашего Worker:

export default {
	async fetch(request, env, ctx) {
		return new Response(`API host: ${env.API_HOST}`);
	},
};

export interface Env {
	API_HOST: string;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		return new Response(`API host: ${env.API_HOST}`);
	},
} satisfies ExportedHandler<Env>;

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        # Environment variables are accessed via attribute access on self.env
        return Response(f"API host: {self.env.API_HOST}")

Также можно импортировать env от cloudflare:workers для доступа к переменным окружения из любого места в коде, в том числе за пределами обработчиков запросов:

import { env } from "cloudflare:workers";

// Access environment variables at the top level
const apiHost = env.API_HOST;

export default {
	async fetch(request) {
		return new Response(`API host: ${apiHost}`);
	},
};

import { env } from "cloudflare:workers";

// Access environment variables at the top level
const apiHost = env.API_HOST;

export default {
	async fetch(request: Request): Promise<Response> {
		return new Response(`API host: ${apiHost}`);
	},
};

Такой подход удобен, когда вам нужно:

• Инициализируйте конфигурацию или клиенты API на верхнем уровне своего Worker.
• Доступ к переменным окружения из глубоко вложенных функций без передачи env через каждый вызов функции.

Подробнее см. в Импорт env как глобальный.

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

В примере ниже настраиваются два окружения, staging и production, с разными значениями для API_HOST.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker-dev",
	// top level environment
	"vars": {
		"API_HOST": "api.example.com"
	},
	"env": {
		"staging": {
			"vars": {
				"API_HOST": "staging.example.com"
			}
		},
		"production": {
			"vars": {
				"API_HOST": "production.example.com"
			}
		}
	}
}

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

[vars]
API_HOST = "api.example.com"

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

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

Чтобы выполнять команды Wrangler в конкретных средах, можно передать --env или -e флаг. Например, вы можете разрабатывать Worker в окружении с именем staging выполнив npx wrangler dev --env staging, и разверните его с помощью npx wrangler deploy --env staging.

Подробнее о окружения в Wrangler.

Чтобы добавить переменные окружения через панель управления:

1. На панели управления Cloudflare перейдите к разделу Workers & Pages страницу.

   Перейдите в Workers & Pages ↗

2. В Обзор, выберите ваш Worker.

3. Выберите Настройки.

4. В разделе Переменные и секреты, выберите Add.

5. Выберите Тип, введите Имя переменной, и введите его Значение. Эта переменная будет доступна вашему Worker.

6. (Необязательно) Чтобы добавить несколько переменных окружения, выберите Добавить переменную.

7. Выберите Развернуть чтобы внести свои изменения.

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

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

При включении nodejs_compat и nodejs_compat_populate_process_env флаг совместимости (включён по умолчанию при дате совместимости 2025-04-01 или позже), переменные окружения доступны через глобальный process.env.

process.env будет заполнен лениво, в первый раз, когда process используется в worker.

Значения текстовых переменных передаются напрямую.

Значения JSON-переменных, которые приводятся к строковому типу, передаются в виде разобранного значения.

Значения JSON-переменных, которые не приводятся к строковому типу, передаются в виде необработанной JSON-строки.

Например, представьте себе Worker с тремя переменными окружения, двумя текстовыми значениями и одним значением JSON:

[vars]
FOO =  "abc"
BAR =  "abc"
BAZ = { "a": 123 }

Переменные окружения можно добавить с помощью wrangler.{json|jsonc|toml} файл, либо через dashboard Cloudflare.

Значения process.env.FOO и process.env.BAR каждый будет строкой JavaScript "abc".

Значение process.env.BAZ будет строкой в формате JSON "{ \"a\": 123 }".

• Перенос переменных окружения из Формат Service Worker в синтаксис ES modules.