Next.js 升級協定
Next.js 版本升級的自動化及手動遷移步驟(例如 v14 → v15)。
優先級:P1(營運級)
實作指南
- 升級偵測:永遠檢查
package.json中next、react和react-dom的版本。 - 規劃:針對主要版本跳升(v13 到 v15),執行增量升級(v13 -> v14,然後 v14 -> v15)。遵循官方 Next.js 遷移指南。
- 自動化 Codemod:使用
npx @next/codemod@latest <transform> <path>來自動化語法遷移。 - 重大變更(v15):回應
next-async-request-api轉換,確保params、searchParams、cookies()和headers()都已await。 - React 一致性:升級
react與react-dom以符合 Next.js 的對等依賴(例如 Next.js 15 需搭配 React 19)。 - 驗證:在每個增量步驟後執行
next dev和next build。檢查主控台錯誤中的水合警告。 - 回報:將所有 codemod 失敗或需要手動修復的部分回報給團隊。
3. 依賴更新
同步升級 Next.js 與對等依賴:
# 使用 npm
npm install next@latest react@latest react-dom@latest
# 更新型別
npm install --save-dev @types/react@latest @types/react-dom@latest
4. 手動驗證規則
- 非同步上下文:驗證所有
cookies()、headers()以及路由params的使用皆已await。 - 元資料:確保
generateMetadata的型別符合新的非同步params簽章。 - 快取:在 v15+,
fetch預設為{ cache: 'no-store' }。若需舊版行為,請明確設定{ cache: 'force-cache' }。
5. 測試建置
- 在 codemod 與套件更新後立即執行
npm run build。 - 若使用
--turbo,檢查是否有「Hydration failed」或「Turbopack」相容性錯誤。
反模式
- 勿跳過主要版本:一次只升級一個主要版本(13→14,再 14→15)。
- 勿手動修復重大變更:永遠先執行
npx @next/codemod@latest轉換。 - 勿預設升級後快取行為不變:v15 預設為
no-store;需審查所有fetch呼叫。 - 勿在 Pages Router 中使用非同步頁面函式:
export default async function Page()會導致致命錯誤。