← Cloudflare Workers / workers / configuration

Proměnné prostředí

Pro připojení textových řetězců nebo hodnot JSON k Workeru můžete přidat proměnné prostředí, což je typ bindingu. Proměnné prostředí jsou dostupné na env parametr předaný do vašeho Workeru fetch obslužná rutina události.

Textové řetězce a hodnoty JSON nejsou šifrované a hodí se pro ukládání konfigurace aplikace.

Chcete-li přidat proměnné prostředí pomocí Wrangler, definujte text a JSON přes [vars] konfigurace ve vašem souboru Wrangler. V následujícím příkladu API_HOST a API_ACCOUNT_ID jsou textové hodnoty a SERVICE_X_DATA je hodnota 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

Následující příklad ukazuje, jak přistupovat k API_HOST proměnnou prostředí v kódu vašeho Workeru:

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}")

Můžete také importovat env z cloudflare:workers pro přístup k proměnným prostředí odkudkoli ve vašem kódu, včetně míst mimo request handlery:

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}`);
	},
};

Tento přístup je užitečný, když potřebujete:

• Inicializujte konfiguraci nebo API klienty na nejvyšší úrovni svého Workeru.
• Přistupujte k proměnným prostředí i z hluboko zanořených funkcí, aniž byste je museli předávat env při každém volání funkce.

Podrobnosti uvádí Import env jako globální.

Prostředí ve Wrangleru vám umožňují určit odlišné konfigurace pro stejný Worker, včetně odlišných hodnot pro vars v každém prostředí. Jak vars je nedědičný klíč, prostředí je nedědí a je nutné je zadat pro každé prostředí zvlášť.

Níže uvedený příklad nastavuje dvě prostředí, staging a production, s různými hodnotami pro 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"

Chcete-li spouštět příkazy Wrangleru v konkrétních prostředích, můžete předat --env nebo -e příznak. Worker můžete například vyvíjet v prostředí nazvaném staging spuštěním npx wrangler dev --env staging, a nasaďte jej pomocí npx wrangler deploy --env staging.

Přečtěte si o prostředí ve Wrangleru.

Chcete-li přidat proměnné prostředí přes dashboard:

1. V dashboardu Cloudflare přejděte na Workers & Pages stránce.

   Přejděte na Workers & Pages ↗

2. V Přehled, vyberte svého Workera.

3. Vyberte Nastavení.

4. V části Proměnné a tajné klíče, vyberte Přidat.

5. Vyberte Typ, zadejte Název proměnné, a zadejte jeho Hodnota. Tato proměnná bude ve Workeru k dispozici.

6. (Optional) To add multiple environment variables, select Přidat proměnnou.

7. Vyberte Nasadit k implementaci vašich změn.

Tajné klíče jsou proměnné prostředí. Rozdíl je v tom, že hodnoty secret nejsou po nastavení viditelné ve Wrangler ani v Cloudflare dashboardu. Citlivá data, včetně hesel nebo API tokenů, by proto měla být vždy šifrovaná, aby nedošlo k jejich úniku. Pro váš Worker není mezi proměnnou prostředí a secret žádný rozdíl. Hodnota secret se předává tak, jak byla definována.

Uložte secrets pro použití při lokálním vývoji buď do .dev.vars soubor nebo .env soubor ve stejném adresáři jako konfigurační soubor Wrangleru.

Tyto soubory by měly být formátovány pomocí dotenv ↗ syntax. Například:

SECRET_KEY="value"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

Chcete-li nastavit různé tajné klíče pro každé prostředí Cloudflare, vytvořte soubory s názvem .dev.vars.<environment-name> nebo .env.<environment-name>.

Když v lokálním vývoji vyberete prostředí Cloudflare, načte se nejprve soubor specifický pro dané prostředí, a to před obecným .dev.vars (nebo .env) soubor.

• Při použití .dev.vars.<environment-name> soubory, všechny secrets musí být definovány pro každé prostředí zvlášť. Pokud .dev.vars.<environment-name> existuje, načte se jen ten; .dev.vars soubor se nenačte.
• Naproti tomu všechny odpovídající .env soubory se načtou a hodnoty se sloučí. Pro každou proměnnou se použije hodnota z nejspecifičtějšího souboru, a to v tomto pořadí priority:
  • .env.<environment-name>.local (nejvíce specifické)
  • .env.local
  • .env.<environment-name>
  • .env (nejméně specifické)

Když zapnete nodejs_compat a nodejs_compat_populate_process_env příznak kompatibility (u dat kompatibility od 2025-04-01 včetně je ve výchozím nastavení povolen), jsou proměnné prostředí dostupné přes globální process.env.

process.env se naplní až v okamžiku, kdy poprvé process je použita ve workeru.

Hodnoty textových proměnných jsou zpřístupněny přímo.

Hodnoty proměnných JSON, které se vyhodnotí jako řetězcové hodnoty, jsou zpřístupněny jako parsovaná hodnota.

Hodnoty proměnných JSON, které se nevyhodnotí jako řetězcové hodnoty, jsou zpřístupněny jako nezpracovaný řetězec JSON.

Představte si například Worker se třemi proměnnými prostředí, dvěma textovými hodnotami a jednou hodnotou JSON:

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

Proměnné prostředí lze přidat buď pomocí wrangler.{json|jsonc|toml} soubor, nebo přes rozhraní Cloudflare dashboardu.

Hodnoty process.env.FOO a process.env.BAR budou vždy řetězcem JavaScriptu "abc".

Hodnota process.env.BAZ bude řetězec zakódovaný do JSON "{ \"a\": 123 }".

• Migrace proměnných prostředí z formátu Service Worker do syntaxe ES modules.