部署

随处部署

Cloudflare Workers 是第一个原生支持的目标，体验最顺滑；其他平台可通过 Nitro Vite 插件获得，覆盖 Vercel、Netlify、AWS、Deno Deploy 等。

Cloudflare Workers

vinext 通过 @cloudflare/vite-plugin 与 Cloudflare Workers 原生集成，包括通过 cloudflare:workers 访问 bindings、KV 缓存、图片优化，以及 @vinext/cloudflare deploy 的一条命令工作流。

身份认证——二选一

cf auth login本地开发推荐

打开浏览器窗口完成认证。

CLOUDFLARE_API_TOKENCI / 非交互场景

在 dash.cloudflare.com/profile/api-tokens 使用 Edit Cloudflare Workers 模板创建令牌。该模板授予了 @vinext/cloudflare deploy 所需的全部权限。

账户 ID

在 cloudflare.config.ts 的defineConfig 顶层、worker 之外设置accountId。你可以在 Cloudflare 仪表盘 URL（dash.cloudflare.com/<account-id>）中找到你的账户 ID。或者，设置 CLOUDFLARE_ACCOUNT_ID 环境变量，而不是把它硬编码进配置文件。

一条命令部署

$npx @vinext/cloudflare deploy

$vp exec vinext-cloudflare deploy

$npx @vinext/cloudflare deploy --env staging

$vp exec vinext-cloudflare deploy --env staging

@vinext/cloudflare deploy会校验初始化好的配置、构建应用，并用 cf部署其 Cloudflare Build Output，而不会改写项目配置。使用--env <name> 来选择构建与部署所用的 Vite 模式。--preview 是 --env preview 的简写。

Response Store 模式

在 Response Store 的 service-binding 模式下，两个 Worker 会一起构建，但缓存 Worker 需要显式部署。在创建 init 指定的 R2 存储桶后，运行：

终端

bash

pnpm run build:vinext
pnpm run deploy:response-store
pnpm run deploy:vinext

对于 create-vinext-app 项目，使用build 与deploy，而非build:vinext 与deploy:vinext。仅当 Response Store 的包或配置发生变化时才重新部署它；普通的应用部署不会部署这些辅助 Worker。

缓存适配器

缓存是可插拔的。默认的 MemoryCacheHandler 开箱即用；在生产环境中，与其在 worker 入口以命令式方式接线缓存处理器，不如在vinext() 插件配置中声明它们。@vinext/cloudflare 附带了 Cloudflare 适配器： KV 数据缓存（kvDataAdapter()）、 Workers Cache CDN（workersCacheCdnAdapter()）、静态资源（staticAssetsAdapter()）与 Response Store（responseStoreAdapter()）。 KV 与 Workers Cache 适配器填充不同的槽位，可组合使用：

vite.config.ts

import { workersCacheCdnAdapter } from "@vinext/cloudflare/cache/workers-cache-cdn-adapter";
import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter";

vinext({
  cache: {
    cdn: workersCacheCdnAdapter(),
    data: kvDataAdapter(),
  },
});

KV 数据适配器在运行时读取 env[binding]。请在 cloudflare.config.ts中配置它的命名空间与 Workers Cache 入口点。这里的existingExports是你当前 Worker 的 exports 对象，如果没有则为{}：

cloudflare.config.ts

import { bindings } from "cf/config";
import { createWorkersCacheConfig } from "@vinext/cloudflare/cache/config";

const cache = await createWorkersCacheConfig();

defineWorker({
  // ...已有的 Worker 设置
  ...cache,
  env: {
    // ...已有的 bindings
    ...cache.env,
    VINEXT_KV_CACHE: bindings.kv(),
  },
  exports: { ...existingExports, ...cache.exports },
});

binding 默认为VINEXT_KV_CACHE，因此只要你的绑定名就是这个，kvDataAdapter() 不带选项也能工作。其他选项：appPrefix（为命名空间缓存键加前缀，以在单个 KV 命名空间内隔离多个应用）、ttlSeconds（默认 KV expirationTtl，默认 30 天）、tagCacheTtlMs（内存中标签失效缓存 TTL，默认 5s），以及 entryCacheTtlSeconds（可选的 KV 边缘缓存 TTL，用于条目读取；标签标记保留 KV 默认值）。完整细节见caching guide。

App Router 与 Pages Router 在 Workers 上都支持完整的客户端水合。

Cloudflare Bindings（D1、R2、KV、AI 等）

使用 import { env } from "cloudflare:workers" 即可在任何服务端组件、路由处理器或 Server Action 中访问 bindings。无需自定义的 worker 入口或特殊配置。

app/page.tsx

tsx

import { env } from "cloudflare:workers";

export default async function Page() {
  const result = await env.DB.prepare("SELECT * FROM posts").all();
  return <div>{JSON.stringify(result)}</div>;
}

这之所以可行，是因为 @cloudflare/vite-plugin在 workerd 中运行 RSC 环境，而 cloudflare:workers在那里是一个原生模块。在生产构建中，该导入会被外部化，由 workerd 在运行时解析。所有绑定类型都受支持：D1、R2、KV、Durable Objects、AI、Queues、Vectorize、Browser Rendering 等。

在 cloudflare.config.ts 中声明 bindings

cloudflare.config.ts

import { bindings } from "cf/config";

env: {
  // ...已有的 bindings
  DB: bindings.d1({ name: "my-db" }),
  CACHE: bindings.kv(),
},

流量感知预热

流量感知预热会在部署时查询 Cloudflare 的 zone 分析数据，挑选出真正有流量的路由。这些路由随后会经过 vinext 标准的、分阶段的 CDN 预热流程，包括路由解析、可缓存性检查与晋升。

$npx @vinext/cloudflare deploy --traffic-aware-warm-cache

预热覆盖 90% 流量的路由

$vp exec vinext-cloudflare deploy --traffic-aware-warm-cache

同上，配合 Vite+

$npx @vinext/cloudflare deploy --traffic-aware-warm-cache --traffic-aware-coverage 95

更激进的覆盖率

$npx @vinext/cloudflare deploy --traffic-aware-warm-cache --traffic-aware-limit 500

上限 500 条路由

$npx @vinext/cloudflare deploy --traffic-aware-warm-cache --traffic-aware-window 48

使用 48 小时的分析数据

$npx @vinext/cloudflare deploy --traffic-aware-warm-cache --warm-cache-target https://example.com

手动设置生产源站

需要一个自定义域名（*.workers.dev 上无法使用 zone 分析数据），以及具备该 zone 的 Zone > Analytics > Read 与Zone > Zone > Read 权限的 CLOUDFLARE_API_TOKEN。

对于类型化配置的项目，在 cloudflare.config.ts 中用domains: ["example.com"] 在 Worker 上声明自定义域名。生成的 Build Output 中的第一个域名会被同时用于分析与分阶段预热。Wrangler 项目则从它们配置好的路由与已部署的触发器保留域名选择。使用 --warm-cache-target https://example.com 可覆盖源站。添加 --warm-cache-certify 以要求可复用的缓存命中在晋升前被证明有效，或使用 --no-promote 让预热好的版本停留在 0% 流量以便验证。

单独使用流量感知标志即可应用覆盖率与路由上限。把它与 --warm-cache 组合则会保留完整的、构建期发现的预热结果。所有选择项与要求的详细说明见caching guide。此前的 --experimental-traffic-aware-warm-cache、--experimental-tpr、--tpr-* 名称仍作为别名保留。

自定义 Vite 配置

如果你需要自定义 Vite 配置，请创建 vite.config.ts。vinext 会把它的配置与你的配置合并。

对于使用 App Router 的 Cloudflare Workers 部署，请配置 @cloudflare/vite-plugin，让 RSC 环境运行在 workerd 中：

vite.config.ts

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

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

Module Federation（客户端）

对于客户端 Module Federation，需要在 host 与 remote 两侧都把 React 与 React DOM 配置为单例共享模块。

vite.config.ts

import { federation } from "@module-federation/vite";
import { defineConfig } from "vite";
import vinext from "vinext";

export default defineConfig({
  plugins: [
    federation({
      name: "host",
      shared: {
        react: { singleton: true },
        "react/": { singleton: true },
        "react-dom": { singleton: true },
        "react-dom/": { singleton: true },
      },
    }),
    vinext(),
  ],
});

在一个远程客户端组件中，读取 React hooks 之前先使用 getVinextReact()。 vinext 会在应用模块执行前注册 host 的浏览器 React 实例，并且首次注册在远程求值与 HMR 之间保持稳定：

remote/Counter.tsx

tsx

"use client";

import * as React from "react";
import { getVinextReact } from "vinext/client";

const { useState } = getVinextReact(React);

export function RemoteCounter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount((value) => value + 1)}>{count}</button>;
}

这个桥接仅限浏览器。它不提供 App Router 的 Module Federation SSR，也不会透明地替换第三方包内部的 React 导入；兼容的 React 版本仍由 Module Federation 的 shared 配置负责。完整可用配置见 examples。

其他平台（via Nitro）

要部署到 Cloudflare 以外的平台，vinext 可以与 Nitro 作为 Vite 插件配合使用。在 Vite 配置中把 nitro 与 vinext 并列，即可部署到任意 Nitro 支持的平台。

vite.config.ts

import { defineConfig } from "vite";
import vinext from "vinext";
import { nitro } from "nitro/vite";

export default defineConfig({
  plugins: [vinext(), nitro()],
});

终端

bash

npm install nitro

Nitro 在绝大多数 CI/CD 环境（Vercel、Netlify、AWS Amplify、Azure 等）中会自动探测部署平台，因此通常你不需要设置 preset。对于本地构建，请设置 NITRO_PRESET 环境变量：

终端

bash

NITRO_PRESET=vercel npx vite build
NITRO_PRESET=netlify npx vite build
NITRO_PRESET=deno_deploy npx vite build

说明

vinext 通过 @cloudflare/vite-plugin 与 Workers 原生集成，包括 cloudflare:workers bindings、KV 缓存、图片优化与一条命令部署。

部署 / 构建命令

$npx @vinext/cloudflare deploy

先运行 vinext init --platform=cloudflare 安装 cf 与 Cloudflare Vite plugin v2，生成 cloudflare.config.ts
认证二选一：cf auth login（本地开发）或 CLOUDFLARE_API_TOKEN 环境变量（CI / 非交互）
在 cloudflare.config.ts 的 defineConfig 顶层设置 accountId，或使用 CLOUDFLARE_ACCOUNT_ID 环境变量
运行 npx @vinext/cloudflare deploy —— 校验配置、构建并部署 Cloudflare Build Output

完整的支持平台列表与各家提供商的特定配置见Nitro 部署文档。更多平台的原生适配器已在规划中。