迁移 Next.js 到 vinext

vinext 在 Vite 上重新实现了 Next.js 的 API 接口。现有的 app/、pages/ 和 next.config.js 无需修改即可直接使用——迁移过程仅是替换包、生成配置和转换为 ESM。无需更改应用程序代码。

第一步：验证 Next.js 项目

确认 package.json 的 dependencies 或 devDependencies 中包含 next。如果未找到，停止——此技能不适用。

根据锁文件检测包管理器：

检测路由模式：如果根目录或 src/ 下存在 app/ 目录，则为 App Router。如果仅存在 pages/ 目录，则为 Pages Router。两者可以共存。

快速参考

第一阶段：检查兼容性

运行 vinext check（如需，可先通过 npx vinext check 安装 vinext）。查看评分报告。如果存在严重的不兼容问题，请在继续前告知用户。

有关支持/不支持的功能以及生态库状态，请参阅 references/compatibility.md。

第二阶段：自动迁移（推荐）

运行 vinext init。此命令将：

1. 运行 vinext check 以获取兼容性报告
2. 将 vite 安装为开发依赖（如果是 App Router，还会安装 @vitejs/plugin-rsc）
3. 向 package.json 添加 "type": "module"
4. 重命名 CJS 配置文件（例如，postcss.config.js → .cjs）以避免 ESM 冲突
5. 向 package.json 添加 dev:vinext 和 build:vinext 脚本
6. 生成一个最小化的 vite.config.ts

此过程不会破坏现有代码——原有的 Next.js 配置仍可与 vinext 并存。在完全切换之前，使用 dev:vinext 脚本进行测试。

如果 vinext init 成功，请跳到第四阶段（验证）。如果失败或用户倾向于手动控制，则继续第三阶段。

第三阶段：手动迁移

当 vinext init 无法工作或用户希望完全控制时，使用此方法作为备选方案。

3a. 替换包

# 以 npm 为例：
npm uninstall next
npm install vinext
npm install -D vite
# 仅限 App Router：
npm install -D @vitejs/plugin-rsc

3b. 更新脚本

替换 package.json 脚本中所有 next 命令：

保留标志：next dev --port 3001 → vinext dev --port 3001。

3c. 转换为 ESM

向 package.json 添加 "type": "module"。重命名任何 CJS 配置文件：

• postcss.config.js → postcss.config.cjs
• tailwind.config.js → tailwind.config.cjs
• 任何其他使用 module.exports 的 .js 配置文件

3d. 生成 vite.config.ts

有关针对不同路由器和部署目标的配置变体，请参阅 references/config-examples.md。

Pages Router（最小化）：

import vinext from "vinext";
import { defineConfig } from "vite";
export default defineConfig({ plugins: [vinext()] });

App Router（最小化）：

import vinext from "vinext";
import { defineConfig } from "vite";
export default defineConfig({ plugins: [vinext()] });

当未明确将 rsc 选项设置为 false 时，vinext 会自动为 App Router 注册 @vitejs/plugin-rsc。本地开发无需手动配置 RSC 插件。

第四阶段：部署（可选）

选项 A：Cloudflare Workers（推荐用于 Cloudflare）

如果用户希望部署到 Cloudflare Workers，请使用 vinext deploy。它会自动生成 wrangler.jsonc、worker 入口和 Vite 配置（如果缺失），安装 @cloudflare/vite-plugin 和 wrangler，然后构建并部署。

对于手动设置或自定义 worker 入口，请参阅 references/config-examples.md。

Cloudflare 绑定（D1, R2, KV, AI 等）

要访问 Cloudflare 绑定（D1, R2, KV, AI, Queues, Durable Objects 等），在任何服务器组件、路由处理程序或服务器操作中使用 import { env } from "cloudflare:workers"：

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 中运行服务器环境，而 cloudflare:workers 在其中是一个原生模块。无需自定义 worker 入口，无需 getPlatformProxy()，无需特殊配置。只需导入并使用即可。

绑定必须在 wrangler.jsonc 中定义。对于 TypeScript 类型，运行 wrangler types。

重要提示： 不要使用 getPlatformProxy()、getRequestContext() 或带有 fetch(request, env) 的自定义 worker 入口来访问绑定。这些是较旧的模式。cloudflare:workers 是推荐的方法，并且可以与 vinext 直接使用。

选项 B：其他平台（通过 Nitro）

要部署到 Vercel、Netlify、AWS、Deno Deploy 或任何其他 Nitro 支持的平台，请添加 Nitro Vite 插件：

npm install nitro

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

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

构建并部署：

NITRO_PRESET=vercel npx vite build    # Vercel
NITRO_PRESET=netlify npx vite build   # Netlify
NITRO_PRESET=deno_deploy npx vite build  # Deno Deploy
NITRO_PRESET=node npx vite build      # Node.js 服务器

在大多数 CI/CD 环境中，Nitro 会自动检测平台，因此通常无需设置预设。

注意： 对于 Cloudflare Workers，Nitro 也能工作，但为了获得最佳的开发者体验（包括 cloudflare:workers 绑定、KV 缓存和一键部署），推荐使用原生集成（vinext deploy / @cloudflare/vite-plugin）。

第五阶段：验证

1. 运行 vinext dev 启动开发服务器
2. 确认服务器无错误启动
3. 浏览关键路由并检查功能
4. 向用户报告结果——如果发生错误，共享完整的输出

有关常见的迁移错误，请参阅 references/troubleshooting.md。

已知限制

反模式

• 不要修改 app/、pages/ 或应用程序代码。 vinext 会 shim 所有 next/* 导入——无需重写导入。
• 不要在应用程序代码中将 next/* 导入重写为 vinext/*。像 next/image、next/link、next/server 这样的导入会自动解析。
• 不要将 webpack/Turbopack 配置复制到 Vite 配置中。请改用 Vite 原生插件。
• 不要跳过兼容性检查。在迁移前运行 vinext check 以尽早发现问题。
• 不要删除 next.config.js，除非你打算用 next.config.ts 或 .mjs 替换它。vinext 会读取它以获取重定向、重写、标头、basePath、国际化、图像和环境变量配置。
• 不要使用 getPlatformProxy() 或自定义 worker 入口来获取绑定。请改用 import { env } from "cloudflare:workers"。这是现代模式，并且可以与 vinext 和 @cloudflare/vite-plugin 直接使用。
• 对于 Cloudflare Workers，优先选择原生集成而非 Nitro。 vinext deploy / @cloudflare/vite-plugin 通过 cloudflare:workers 绑定、KV 缓存和图像优化提供了最佳体验。Nitro 也适用于 Cloudflare，但推荐使用原生设置。