Vite 环境

Vite Environment API ↗ 在 Vite 6 中发布，是 Cloudflare Vite 插件将 Vite 直接与 Workers 运行时集成的关键功能。 作为最终用户，不必了解 Environment API 的所有细节，但了解其高层概念很有用。

Vite 默认创建两个环境：client 和 ssr。 纯前端应用程序使用 client 环境，而使用框架创建的全栈应用程序通常将 client 环境用于前端代码，将 ssr 环境用于服务端渲染。

默认情况下，使用 Cloudflare Vite 插件添加 Worker 时，会创建额外的环境。 其名称派生自 Worker 名称，所有短划线替换为下划线。 此名称可用于在 Vite 配置中引用环境，以应用特定于环境的配置。

在以下示例中，我们有一个名为 my-worker 的 Worker，它与名为 my_worker 的 Vite 环境关联。 我们使用 Vite 配置为此环境设置全局常量替换：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"main": "./src/index.ts"
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-17"
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。

如果你将 Cloudflare Vite 插件与 TanStack Start ↗ 或 React Router v8 ↗ 一起使用，则 Worker 用于服务端渲染并与框架紧密集成。 为支持此功能，应通过在插件配置中设置 viteEnvironment.name 将其分配给 ssr 环境。

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 作为框架构建输出的一部分包含在内。