← Cloudflare Workers / workers / vite-plugin / reference

Окружения Vite

Vite Environment API ↗, выпущенный в Vite 6, является ключевой возможностью, которая позволяет плагину Cloudflare Vite интегрировать Vite напрямую со средой выполнения Workers. Конечному пользователю не обязательно разбираться во всех тонкостях Environment API, однако полезно иметь общее представление о нём.

По умолчанию Vite создаёт два окружения: client и ssr. Приложение только с фронтендом использует client окружение, тогда как full-stack приложение, созданное с использованием фреймворка, обычно использует client окружение для клиентского кода и ssr окружение для серверного рендеринга.

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

В следующем примере у нас есть Worker с именем my-worker который связан с окружением Vite с именем my_worker. Мы используем конфигурацию Vite, чтобы задать глобальные замены констант для этой среды:

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

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

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	environments: {
		my_worker: {
			define: {
				__APP_VERSION__: JSON.stringify("v1.0.0"),
			},
		},
	},
	plugins: [cloudflare()],
});

Подробнее о параметрах конфигурации Vite см. в Настройка Vite ↗.

Поведение по умолчанию, при котором в качестве имени окружения используется имя Worker, подходит для отдельного Worker, например API, к которому обращается ваше фронтенд-приложение, или вспомогательный Worker к которому обращаются через service bindings.

Если вы используете плагин Cloudflare для Vite с TanStack Start ↗ или React Router v8 ↗, тогда ваш Worker используется для серверного рендеринга и тесно интегрирован с фреймворком. Чтобы это поддерживалось, присвойте его ssr окружение, задав viteEnvironment.name в конфигурации плагина.

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";
import { reactRouter } from "@react-router/dev/vite";

export default defineConfig({
	plugins: [cloudflare({ viteEnvironment: { name: "ssr" } }), reactRouter()],
});

Это объединяет конфигурацию окружения Worker с конфигурацией SSR фреймворка и обеспечивает включение Worker в результат сборки фреймворка.