认识 Vinext:基于 Vite 构建的 Next.js 替代方案

Vinext 是 Cloudflare 推出的一款开源 Vite 插件,它重新实现了 Next.js API,使现有的 App Router 或 Pages Router 代码库可以改由 Vite 构建和提供服务,而不再依赖 Next.js 工具链。Cloudflare 于 2026 年 9 月 28 日发布了 1.0 版本。

许多团队喜欢 Next.js,却不喜欢它推着用户走向的托管平台。而仅仅为了更换托管平台就把一个大型应用迁移到另一个框架,代价往往难以接受。Vinext 提供了另一条路径。本文将介绍 Vinext 支持哪些功能、可以部署到哪些平台、在你自己的应用上进行测试所需的具体命令,以及 Cloudflare 自己在文档中列出的尚未覆盖的功能。

Vinext 是什么?它与其他 Next.js 替代方案有何不同?

Vinext 是 Cloudflare 在 Vite 之上重新实现的 Next.js。Vinext 起步于 2026 年 2 月一个为期一周、由 AI 驱动的实验项目,七个月后发布 1.0 版本。README 明确说明它不是 fork:其核心代码完全从零编写,以匹配 Next.js 的公开 API。

因此,Vinext 与常见的 Next.js 替代方案属于不同类型的选择。迁移到 React Router、Astro 或 SvelteKit 意味着要重写路由、数据加载和组件。而 Vinext 不会改动这些代码,只替换负责构建和提供服务的部分。你的项目看起来仍然是一个 Next.js 项目,只是底层由 Vite 完成工作。

Vinext 支持哪些功能?

Vinext 同时支持两种路由器,并覆盖了现代 Next.js 的主要服务端功能。根据 1.0 发布公告和 README,其支持的功能包括:

• App Router、Pages Router,以及同时使用两者的混合应用
• React Server Components 和 Server Actions
• Middleware、API 路由和路由处理程序(route handlers)
• ISR 重新验证
• 通过 generateStaticParams() 和 getStaticPaths() 实现的构建时预渲染
• 通过 output: "export" 实现的静态导出

README 以 Next.js 16.x 为目标版本,并将 vite ^8.0.0 列为 peer dependency。

Cloudflare 以两种不同方式报告 Vinext 与 Next.js 的兼容性,而这两个数字衡量的并不是同一件事。1.0 公告称测试兼容性超过 99%,但仅限于客户需求最高的那些功能,且不包括 Cache Components。README 则表示”约 94% 的 Next.js 16 API 已获得完整或部分支持”。这两个数据都出自 Cloudflare,都无法替代你亲自运行自己的应用来验证。

Vinext 可以部署到哪里?

Vinext 原生支持部署到 Cloudflare Workers,1.0 公告指出它可以运行在 Workers 免费套餐上。同一篇公告还将 Netlify 和 AWS Lambda 列为部署目标。README 解释了其实现机制:Workers 由 @vinext/cloudflare 直接处理,而 Vercel、Netlify、AWS 和 Deno Deploy 则需要添加 Nitro Vite 插件来接入,并不涉及原生的 Netlify 或 Lambda 适配器。

最简配置只需添加一个插件:

// vite.config.ts
import { defineConfig } from "vite";
import vinext from "vinext";

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

如需部署到非 Cloudflare 平台,请安装 nitro 并添加其插件:

// vite.config.ts
import { defineConfig } from "vite";
import vinext from "vinext";
import { nitro } from "nitro/vite";

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

npm install nitro
NITRO_PRESET=netlify npx vite build

如何在现有 Next.js 应用上试用 Vinext

在现有应用上测试 Vinext 只需两条命令,且都不会影响你当前的 Next.js 工作流。建议在一个新分支上运行:

npx vinext check
npx vinext init

vinext check 会扫描项目,在你做出任何改动之前报告已知的不兼容项。vinext init 是非破坏性的,因此 next dev 可以与新配置并存、照常使用。它会询问部署目标,默认选项为 Cloudflare。自 1.0 版本起,Cloudflare 配置默认使用 cf CLI 以及带类型定义的 cloudflare.config.ts。如果想保留旧版的 Wrangler 配置方式,可以传入 --legacy-wrangler-cloudflare-init。

新建 Vinext 应用

对于全新项目,依次完成脚手架搭建、运行、构建和部署:

npm create vinext-app@latest my-app
npx vite dev
npx vite build
npx @vinext/cloudflare deploy

1.0 版本为部署命令新增了 --warm-cache 参数。它会先以 0% 流量上传新版本,通过该版本请求可缓存的页面以预热缓存,之后才将其正式上线。

Vinext 有哪些局限和已知缺口?

README 的 Known gaps 章节列出了 Vinext 目前尚未与 Next.js 对齐的四个方面:Cache Components、构建时图片与字体优化、App Router 开发环境中的原生模块,以及部分平台相关的路由配置。Cloudflare 表示这四项都仍在开发中,因此都不是永久性的限制。

• Cache Components 与 PPR:"use cache" 已部分可用,但完整的 cacheComponents 模型尚未完成。缓存配置文件(cache profiles)、标签(tags)、部分外壳(partial shells)、恢复(resuming)、预取(prefetching)以及部分开发和构建缓存的行为仍可能与 Next.js 不一致。
• **图片与字体:**在 Cloudflare 上,图片可以在请求时进行优化。Vinext 尚未完整复刻 Next.js 在构建时运行的图片处理流水线,字体也是在运行时加载,而非在构建过程中处理。
• **原生模块:**sharp、resvg、satori、lightningcss 和 @napi-rs/canvas 等包在 Vite 的 RSC 开发环境中可能无法正常工作。生产构建能处理的此类包比开发模式更多。
• **路由配置:**Vinext 会忽略 runtime 和 preferredRegion 路由设置。

README 还指出,Vinext 目前还不能作为所有应用的无缝替代品(drop-in replacement)。

谁应该采用 Vinext,谁应该再等等

Vinext 适合希望继续使用 Next.js 编写代码、又不想被绑定在单一托管平台上的团队。关于是否已可用于生产环境,各方资料的说法并不完全一致。Cloudflare 的公告称 1.0 已达到生产可用,而 README 的回答是”可以,但需谨慎”,并指出 Vinext 仍存在兼容性缺口,也尚未在所有类型的生产级 Next.js 应用上得到验证。

• 建议采用:如果你的应用同时使用两种路由器、RSC、Server Actions 和 ISR,并且希望部署到 Workers 或通过 Nitro 部署。
• 建议观望:如果你重度依赖 Cache Components、PPR,或依赖 tags、profiles 等 "use cache" 语义。
• 可考虑 OpenNext:如果你需要经过验证的生产成熟度。Vinext 的 README 解释说,OpenNext 基于 next build 的输出工作,因此覆盖了更多 Next.js API,而且拥有长得多的实践积累。

总结

借助 Vinext,你无需重写 Next.js 应用就能离开 Vercel,但需要接受文档中已列明的缺口,主要集中在 Cache Components 方面。要判断它是否适合你,可以先创建一个分支,运行 npx vinext check,将其标记出的问题与已知缺口逐一对照,然后运行 npx vinext init,并与 next dev 的行为进行比较。如果你还想迁移工具链的其余部分,请阅读 Vite+ 入门指南(README 中列出了适用于 Vite+ 项目的 vp exec vinext-cloudflare deploy)。关于 init 所配置的 cloudflare.config.ts 工作流,请参阅《Cloudflare 全新 cf CLI 实用指南》。

常见问题

迁移到 Vinext 后,我还能保留自定义的 webpack 配置或 next/jest 配置吗?

不能。Vinext 运行在 Vite 之上,因此 Turbopack 和 webpack 配置均不适用,自定义的 webpack loader 或插件必须替换为 Vite 插件。Vinext 的 README 将 next/jest 列为不支持,并推荐改用 Vitest。AMP 同样不受支持,useAmp() 始终返回 false;旧版的 next export 命令则改为在 Next.js 配置中设置 output: 'export' 来实现。

Vinext 需要哪些版本的 React 和 Vite?

Vinext 声明的 peer dependencies 为 react ^19.3.1、react-dom ^19.3.1、react-server-dom-webpack ^19.3.1 和 vite ^8.0.0,目标版本为 Next.js 16.x。App Router 项目还必须安装 @vitejs/plugin-rsc。Vinext 在检测到 app 目录时会自动注册该插件,因此如果你自行添加 rsc() 调用,构建将因插件重复而报错,除非你向 vinext() 传入 rsc: false。

vinext init 会对现有 Next.js 项目做哪些改动?

vinext init 会在 package.json 中添加 'type': 'module',并重命名 CommonJS 配置文件(例如将 postcss.config.js 重命名为 postcss.config.cjs),以避免 ESM 冲突。它还会安装 Vite 和 Vinext 相关包,并在现有 Next.js 脚本之外新增 dev:vinext、build:vinext 和 start:vinext 脚本。由于原有脚本保持不变,next dev 和 Vinext 开发服务器可以在同一代码库中运行,便于并行对比。

在 Cloudflare 上使用 Vinext 时,revalidateTag 会在页面重新生成期间继续提供旧页面吗?

会。从 2026 年 10 月的 1.1 系列版本开始,当你传入缓存配置文件(例如 revalidateTag(tag, 'max'))时即可如此。早期版本会从 Workers Cache 中清除匹配的页面,导致下一个请求需要等待完整渲染。现在,Workers Cache 和 Response Store 会将这些条目标记为过期,并在后台重新生成期间继续提供缓存版本,与 Next.js 的行为一致。如果仅传入 tag 调用 revalidateTag,或设置 expire: 0,条目仍会立即失效。过期的 'use cache' 条目同样会在重新生成期间继续提供。