migrate-to-vinext

将 Next.js 迁移到 vinext

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

第一步：验证 Next.js 项目

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

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

锁文件	管理器	安装命令	卸载命令
pnpm-lock.yaml	pnpm	pnpm add	pnpm remove
yarn.lock	yarn	yarn add	yarn remove
bun.lockb / bun.lock	bun	bun add	bun remove
package-lock.json 或无	npm	npm install	npm uninstall

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

快速参考

命令	用途
vinext check	扫描项目兼容性问题，生成评分报告
vinext init	自动迁移——安装依赖、生成配置、转换为 ESM
vinext dev	开发服务器，支持 HMR
vinext build	生产构建（App Router 支持多环境）
vinext start	本地生产服务器
npx @vinext/cloudflare deploy	构建并部署到 Cloudflare Workers
vp exec vinext-cloudflare deploy	使用 Vite+ 构建并部署到 Cloudflare Workers

阶段 1：检查兼容性

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

参见 references/compatibility.md 了解支持/不支持的功能及生态库状态。

阶段 2：自动迁移（推荐）

运行 vinext init。该命令会：

1. 运行 vinext check 生成兼容性报告
2. 安装 vite 作为 devDependency（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
7. 将 /dist/ 和 .vinext/ 添加到 .gitignore

此操作不会破坏现有配置——现有的 Next.js 设置仍可与 vinext 共存。使用 dev:vinext 脚本进行测试，然后再完全切换。

如果 vinext init 成功，请跳到阶段 4（验证）。如果失败或用户希望手动控制，请继续阶段 3。

阶段 3：手动迁移

当 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	vinext dev	开发服务器，支持 HMR
next build	vinext build	生产构建
next start	vinext start	本地生产服务器
next lint	vinext lint	委托给 eslint/oxlint

保留标志：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 了解不同路由器和部署目标的配置变体。

如果项目已有自定义 Vite 配置，编辑时优先使用 Vite 8 原生键：oxc、optimizeDeps.rolldownOptions 和 build.rolldownOptions。旧的 esbuild 和 build.rollupOptions 设置目前仍可工作，但建议迁移。

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 插件。

3e. 更新 .gitignore

确保忽略 vinext 生成的输出和缓存：

/dist/
.vinext/

阶段 4：部署（可选）

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

如果用户希望部署到 Cloudflare Workers，请使用 npx @vinext/cloudflare deploy。使用 Vite+ 时，运行本地安装的二进制文件时使用 vp exec vinext-cloudflare deploy。它会通过 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 可以工作，但原生集成（npx @vinext/cloudflare deploy / vp exec vinext-cloudflare deploy / @cloudflare/vite-plugin）是推荐的方式，可提供最佳的开发者体验，包括 cloudflare:workers 绑定、KV 缓存和单命令部署。

阶段 5：验证

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

参见 references/troubleshooting.md 了解常见迁移错误。

已知限制

功能	状态
next/image 优化	远程图片通过 @unpic；无构建时优化
next/font/google	通过 CDN 加载，不自托管
基于域名的 i18n	不支持；路径前缀 i18n 可工作
next/jest	不支持；请使用 Vitest
Turbopack/webpack 配置	忽略；请改用 Vite 插件
runtime / preferredRegion	路由段配置被忽略
PPR（部分预渲染）	请改用 "use cache" 指令（Next.js 16 方法）

反模式

• 不要修改 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、i18n、图片和 env 配置。
• 不要使用 getPlatformProxy() 或自定义 Worker 入口来获取绑定。 请改用 import { env } from "cloudflare:workers"。这是现代模式，可与 vinext 和 @cloudflare/vite-plugin 开箱即用。
• 对于 Cloudflare Workers，优先使用原生集成而非 Nitro。 npx @vinext/cloudflare deploy / vp exec vinext-cloudflare deploy / @cloudflare/vite-plugin 提供了最佳体验，包括 cloudflare:workers 绑定、KV 缓存和图片优化。Nitro 也可用于 Cloudflare，但推荐使用原生设置。