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
npx vite dev	启用 HMR 的开发服务器
npx vite 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. 替换软件包

# Example with npm:
npm uninstall next
npm install vinext
npm install -D vite
# App Router only:
npm install -D @vitejs/plugin-rsc

3b. 更新脚本

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

之前	之后	说明
next dev	vite dev	带 HMR 的开发服务器
next build	vite build	生产构建
next start	vinext start	本地生产服务器
next lint	vinext lint	委托给 eslint/oxlint

保留与 Vite 兼容的标志：next dev --port 3001 → vite dev --port 3001。将 Next 专有的构建标志转换为 vite.config.ts 中的 vinext() 选项，而不是将它们传递给 Vite。

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。

IMPORTANT： 不要使用 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 server

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

注意： Nitro 可用于 Cloudflare Workers，但推荐使用原生集成（npx @vinext/cloudflare deploy / vp exec vinext-cloudflare deploy / @cloudflare/vite-plugin），以便通过 cloudflare:workers 绑定、KV 缓存和一键部署获得最佳开发体验。

阶段 5：验证

1. 运行生成的 dev:vinext 脚本（或 npx vite dev）以启动开发服务器
2. 确认服务器启动时没有错误
3. 访问关键路由并检查功能
4. 向用户报告结果；如果出现错误，请提供完整输出

常见迁移错误请参阅 references/troubleshooting.md。

已知限制

功能	状态
next/image 优化	通过 @unpic 加载远程图片；不进行构建时优化
next/font/google	通过 CDN 加载，不可自托管
基于域名的 i18n	不支持；路径前缀 i18n 可用
next/jest	不支持；请使用 Vitest
Turbopack/webpack 配置	会被忽略；请改用 Vite 插件
runtime / preferredRegion	部署位置设置会被忽略；在 cacheComponents 之外，边缘 App Router 页面会跳过 ISR
PPR（部分预渲染）	请改用 "use cache" 指令（Next.js 16 的方案）

反模式

• 请勿修改 app/、pages/ 或应用代码。 vinext 会为所有 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、图片和环境配置。
• 请勿将 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，但推荐使用原生方案。