migrate-to-vinext

將 Next.js 遷移至 vinext

vinext 在 Vite 上重新實作了 Next.js 的 API 表面。現有的 app/、pages/ 和 next.config.js 可直接使用——遷移僅需更換套件、產生設定檔以及轉換為 ESM。應用程式程式碼無需修改。

第一步：確認 Next.js 專案

確認 package.json 中的 dependencies 或 devDependencies 包含 next。若未找到，則停止——此技能不適用。

根據 lockfile 偵測套件管理工具：

Lockfile	管理工具	安裝指令	移除指令
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

第二階段：檢查相容性

執行 vinext check（若尚未安裝 vinext，可先透過 npx vinext check 安裝）。檢視評分報告。若存在重大不相容問題，請先告知使用者再繼續。

支援/不支援的功能及生態系函式庫狀態，請參閱 references/compatibility.md。

第三階段：自動化遷移（建議）

執行 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. 在 .gitignore 中加入 /dist/ 和 .vinext/

此過程不具破壞性——現有的 Next.js 設定仍可與 vinext 並行運作。請先使用 dev:vinext 腳本測試，再完全切換。

若 vinext init 成功，請跳至第五階段（驗證）。若失敗或使用者偏好手動控制，請繼續至第四階段。

第四階段：手動遷移

當 vinext init 無法運作或使用者希望完全掌控時，使用此方式作為備案。

4a. 更換套件

# 以 npm 為例：
npm uninstall next
npm install vinext
npm install -D vite
# 僅 App Router：
npm install -D @vitejs/plugin-rsc

4b. 更新腳本

將 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。

4c. 轉換為 ESM

在 package.json 中加入 "type": "module"。重新命名任何 CJS 設定檔：

• postcss.config.js → postcss.config.cjs
• tailwind.config.js → tailwind.config.cjs
• 其他使用 module.exports 的 .js 設定檔

4d. 產生 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 外掛。

4e. 更新 .gitignore

確保忽略 vinext 產生的輸出和快取：

/dist/
.vinext/

第五階段：部署（選擇性）

選項 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() 或自訂 worker 進入點搭配 fetch(request, env) 來存取繫結。這些是舊模式。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 會自動偵測平台，因此通常無需指定 preset。

注意： 對於 Cloudflare Workers，Nitro 可以運作，但建議使用原生整合（npx @vinext/cloudflare deploy / vp exec vinext-cloudflare deploy / @cloudflare/vite-plugin），以獲得最佳的開發者體驗，包括 cloudflare:workers 繫結、KV 快取和一鍵部署。

第六階段：驗證

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 會自動處理所有 next/* 匯入——無需重寫匯入。
• 請勿在應用程式程式碼中將 next/* 匯入改寫為 vinext/*。 像 next/image、next/link、next/server 等匯入會自動解析。
• 請勿將 webpack/Turbopack 設定複製到 Vite 設定中。 請改用 Vite 原生外掛。
• 請勿跳過相容性檢查。 遷移前請執行 vinext check 以提早發現問題。
• 除非要取代為 next.config.ts 或 .mjs，否則請勿移除 next.config.js。 vinext 會讀取其 redirects、rewrites、headers、basePath、i18n、images 和 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，但建議使用原生設定。