架构

Vite 插件，四步成型

vinext 是一个 Vite 插件。其结果是一个标准的 Vite 应用，恰好与 Next.js API 兼容。

插件流水线

解析 next/* 导入

解析所有 next/* 导入，指向用标准 Web API 与 React 原语重新实现 Next.js API 的本地垫片模块。

扫描文件系统路由

扫描你的 pages/ 与 app/ 目录，构建一套符合 Next.js 约定的文件系统路由器。

生成虚拟入口模块

生成虚拟入口模块，用于 RSC、SSR 与浏览器环境，负责请求路由、组件渲染与客户端水合。

集成 RSC 插件

与 @vitejs/plugin-rsc 集成，以支撑 React Server Components——处理 "use client" / "use server" 指令、RSC 流序列化，以及多环境构建。

路由流程

Pages Router 流程

Request → Vite dev server middleware → Route match → getServerSideProps/getStaticProps
  → renderToReadableStream(App + Page) → HTML with __NEXT_DATA__ → Client hydration

App Router 流程

Request → RSC entry (Vite rsc environment) → Route match → Build layout/page tree
  → renderToReadableStream (RSC payload) → SSR entry (Vite ssr environment)
  → renderToReadableStream (HTML) → Client hydration from RSC stream

项目结构

目录树

packages/vinext/
  src/
    index.ts              # 主插件——解析别名、配置、虚拟模块
    cli.ts                # vinext CLI（dev/build/start/deploy/init/check/lint）
    check.ts              # 兼容性扫描器
    deploy.ts             # Cloudflare Workers 部署
    init.ts               # vinext init——Next.js 应用的一条命令迁移
    client/
      entry.ts            # 客户端水合入口
    routing/
      pages-router.ts     # Pages Router 文件系统扫描器
      app-router.ts       # App Router 文件系统扫描器
    entries/
      app-rsc-entry.ts    # App Router RSC 入口生成器
      app-ssr-entry.ts    # App Router SSR 入口生成器
      app-browser-entry.ts # App Router 浏览器入口生成器
      pages-server-entry.ts # Pages Router SSR 入口生成器
      pages-client-entry.ts # Pages Router 客户端入口生成器
    server/
      dev-server.ts       # Pages Router SSR 请求处理器
      prod-server.ts      # 带压缩的生产服务器
      api-handler.ts      # Pages Router API 路由
      isr-cache.ts        # ISR 缓存层
      middleware.ts       # middleware.ts / proxy.ts 运行器
      metadata-routes.ts  # 基于文件的 metadata 路由扫描器
      instrumentation.ts  # instrumentation.ts 支持
    shims/                # 每个 next/* 模块一个文件（33 个垫片 + 6 个内部）
    build/
      static-export.ts    # output: 'export' 支持
    utils/
      project.ts          # 共享项目工具（ESM、CJS、包管理器探测）
    config/
      next-config.ts      # next.config.js 加载器
      config-matchers.ts  # 配置匹配工具

tests/
  *.test.ts               # Vitest 单元 + 集成测试
  nextjs-compat/          # 从 Next.js 测试套件移植过来的测试
  fixtures/               # 测试应用（pages-basic、app-basic、ecosystem libs）
  e2e/                    # Playwright E2E 测试（5 个项目）

examples/                 # 已部署的演示应用

测试

测试套件包含超过 1,700 个 Vitest 测试与380 个 Playwright E2E 测试。其中包含直接从 Next.js 测试套件和 OpenNext 的 Cloudflare 一致性测试套件移植过来的用例，覆盖路由、SSR、RSC、Server Actions、缓存、Metadata、中间件、流式渲染等。 Vercel 的 App Router Playground 也作为集成测试跑在 vinext 上。详见 tests/nextjs-compat/TRACKING.md。

终端

bash

pnpm test             # Vitest 单元 + 集成测试
pnpm run test:e2e     # Playwright E2E 测试（5 个项目）
pnpm run check        # 格式化、lint 与类型检查
pnpm run lint         # 仅 lint（类型感知的 oxlint）
pnpm run fmt          # 格式化（oxfmt）
pnpm run fmt:check    # 不做写入地检查格式化

E2E 测试覆盖 Pages Router（dev + 生产）、App Router（dev），以及通过wrangler dev在 Cloudflare Workers 上运行的两种路由器。

本地搭建（从源码）

如果你是从仓库工作，而不是从 npm 安装：

终端

bash

git clone https://github.com/cloudflare/vinext.git
cd vinext
pnpm install
pnpm run build

这会把 vinext 包构建到 packages/vinext/dist/。要进行活跃开发，请使用 pnpm --filter vinext run dev在变更时重新构建。

要针对一个外部的 Next.js 应用使用它，请链接构建好的包：

终端

bash

# 在你的 Next.js 项目目录下：
pnpm link /path/to/vinext/packages/vinext

或者把它作为文件依赖加入你的 package.json：

package.json

json

{
  "dependencies": {
    "vinext": "file:/path/to/vinext/packages/vinext"
  }
}