next-upgrade

next-upgrade 技能總覽

next-upgrade 會做什麼

next-upgrade 技能會依照官方 migration guides 與 codemods，協助代理把真實的 Next.js 專案升級到較新的 major 版本，而不是憑記憶猜測。它的工作重點很務實：先找出你的 app 目前使用的 next 版本、規劃最安全的升級路徑、優先套用正確的 codemods，接著再更新相依套件，並檢查仍需手動處理的 breaking changes。

哪些人適合使用這個 next-upgrade 技能

這個技能特別適合正在維護既有 Next.js 程式碼庫、希望讓 AI 助手規劃或執行升級，同時盡量貼近官方指引的開發者。尤其在以下情況特別有幫助：

• 你的專案落後超過一個 major 版本
• 你想要的是看得懂 repo 結構的升級計畫，不是泛用清單
• 你需要協助辨識各版本對應的 codemods 與相依套件對齊方式
• 你希望在 Code Editing 工作流程內直接完成，而不只是拿到瀏覽器摘要

真正要解決的工作

多數使用者並不是需要「Next.js 升級資訊」而已。他們真正要的是：把一個目前可正常運作的 app 升到較新的 Next.js 版本，同時不要弄壞 routing、React 相容性、build 輸出或 runtime APIs。next-upgrade 技能就是為了這條決策與執行路徑而設計。

next-upgrade 與一般 prompt 有什麼不同

一般 prompt 可能只會給你寬泛的升級建議。next-upgrade 更聚焦、也更實用，因為它的流程是圍繞這些步驟設計的：

• 先讀取你的 package.json
• 查對目標版本的官方 Next.js 升級指南
• 以漸進方式處理 major 版本跳升
• 優先使用官方 codemods，再考慮手動修改
• 正確搭配升級 next、react 與 react-dom

它不會替你完成的事

這個技能不會取代驗證工作。它可以引導程式碼修改與相依套件更新，但你仍然需要實際執行 app、tests、lint 與 build 檢查。對於高度客製化的環境，例如 monorepo、特殊 bundler 整合，或深度修改過 server/runtime 行為的專案，它也不能取代你對框架與架構本身的理解。

如何使用 next-upgrade 技能

next-upgrade 的安裝情境

請先把這個技能安裝到你的 AI coding 環境，讓它能在你要升級的 repository 裡被直接呼叫。常見安裝方式如下：

npx skills add https://github.com/vercel-labs/next-skills --skill next-upgrade

如果你的環境已經能直接存取來自 vercel-labs/next-skills 的 GitHub skills，你可能只需要直接呼叫 next-upgrade。

實務上怎麼呼叫 next-upgrade

這個 repository 顯示的參數提示是 [target-version]，因此最乾淨的用法是直接指定你要升級到的版本，例如：

• Use next-upgrade for Next.js 16
• Run next-upgrade targeting v15
• Apply the next-upgrade skill to move this app from 13 to 15 incrementally

如果你還不確定目標版本，可以先請它出升級規劃：

• Use next-upgrade to inspect this repo and recommend the safest target version

這個技能需要哪些輸入

當代理可以檢查以下內容時，next-upgrade 會發揮最佳效果：

• package.json
• lockfile，例如 package-lock.json、pnpm-lock.yaml 或 yarn.lock
• 如果 app 在 monorepo 裡，還要有 workspace 設定
• app 目錄結構，尤其是你使用 app/ 還是 pages/
• 用來驗證升級結果的 CI 或 build 指令

最低限度但仍有用的輸入包括：

• 目前的 Next.js 版本
• package manager
• 目標版本
• 你是只要規劃，還是要它實際修改程式碼

把模糊需求變成高品質的 next-upgrade prompt

較弱的 prompt：

• Upgrade my app

較好的 prompt：

• Use next-upgrade to inspect package.json, determine the current Next.js version, upgrade this project to Next.js 15 using official migration guides, run the relevant @next/codemod transforms first, then update next/react/react-dom together and summarize any manual follow-up changes.

如果你的 repo 較複雜，最佳 prompt 會像這樣：

• Use next-upgrade for Code Editing on this monorepo app in apps/web. Read apps/web/package.json, identify the current next/react versions, plan the required incremental major upgrades to reach Next.js 16, apply official codemods where relevant, update dependencies with pnpm-compatible commands, and leave a checklist of manual verification steps for build, routing, and runtime APIs.

這些額外細節能明顯提升輸出品質，因為技能本身很精簡；真正補足 repo 範圍、package manager 與執行邊界的是你的 prompt。

進行修改前，建議採用的 next-upgrade 工作流程

可靠的 next-upgrade usage 流程如下：

1. 檢查 package.json 與目前的相依套件版本
2. 決定目標版本
3. 針對每個 major 升級步驟抓取官方 Next.js 升級指南
4. 先跑 codemods，再做手動清理
5. 更新 next、react 與 react-dom
6. 執行 lint、typecheck、tests 與 production build
7. 修正升級指南或 runtime error 暴露出的其餘 breaking changes

如果你已經落後好幾個版本，不要盲目一次跳升。請明確要求代理把 13 -> 14 -> 15 -> 16 當成分開的升級階段處理。

最先該讀的 repository 檔案

先從上游 repository 的 skills/next-upgrade/SKILL.md 開始：

• https://github.com/vercel-labs/next-skills/tree/main/skills/next-upgrade

這個技能本身不長，因此沒有太多額外的支援檔案需要追。真正的重點在 SKILL.md 編碼好的流程：偵測版本、抓取官方文件、逐步升級、先跑 codemods，最後再更新相依套件。

這個技能依賴的官方文件

這個技能明確指向官方 Next.js 升級資源，包括：

• codemods：https://nextjs.org/docs/app/guides/upgrading/codemods
• 各版本升級指南，例如：
  • https://nextjs.org/docs/app/guides/upgrading/version-16
  • https://nextjs.org/docs/app/guides/upgrading/version-15
  • https://nextjs.org/docs/app/guides/upgrading/version-14

這點對是否值得採用很重要：next-upgrade 的效果，取決於代理是否願意實際抓取並遵循這些官方指南，而不是依賴過時的框架知識。

在 next-upgrade 流程裡，codemods 要先做，不是最後補

next-upgrade guide 最有價值的地方之一，就是它很重視執行順序。它要求代理優先執行官方 codemods：
npx @next/codemod@latest <transform> <path>

技能中提到的例子包括：

• next-async-request-api
• next-request-geo-ip
• next-dynamic-access-named-export

這個順序很重要，因為 codemods 通常能比相依套件升級後再手改，更快、更安全地處理重複性高的 breaking changes。

使用 next-upgrade 時，應明確要求一起更新的相依套件

使用 next-upgrade 時，應明確要求代理一併升級 peer dependencies。這個技能特別強調以下模式：
npm install next@latest react@latest react-dom@latest

即使你實際用的是 pnpm 或 yarn，核心原則也一樣：除非官方指南另有說明，否則應把 next、react 與 react-dom 視為需要協同更新的一組。

next-upgrade 在 Code Editing 情境下的價值

在 Code Editing 模式下，如果你讓代理同時能檢查並修改檔案，而不是只輸出計畫，next-upgrade 會更有價值。適合交給它的任務包括：

• 更新 package.json 中的相依版本範圍
• 套用 codemod 指令
• 修改受 breaking changes 影響的 API
• 留下 inline comments 或 migration summary 供人工複查

如果你的環境無法讀取 repository 檔案或外部文件，它的幫助就會小很多，因為這個技能的優勢正是 repo 檢查搭配官方指南擷取。

next-upgrade 的實際限制與取捨

當你想走一條更有紀律的升級路線時，可以使用 next-upgrade，但也要預期它有一些限制：

• 它不會把每個版本的細節都內建在本地；它預設要即時查官方指南
• 它最適合標準的 Next.js app，不是高度客製化的基礎設施
• 它沒有內建專案專屬的測試自動化
• 遇到 monorepo、子應用或非根目錄 package 檔時，通常需要更明確的提示

簡單說，這個技能能減少猜測，但你的 prompt 仍然要把範圍定義清楚。

next-upgrade 技能常見問題

next-upgrade 會比一般升級 prompt 更好嗎？

通常會，尤其是當你要的是可重複執行的升級流程時。一般 prompt 可能給出看似合理、但其實已過時的建議。next-upgrade 則是建立在官方 migration guides、codemods，以及從你的專案檔案中偵測版本的基礎上。

next-upgrade 技能對新手友善嗎？

友善，但有一個前提：新手最好先用規劃模式。你可以先要求它提供：

• 目前版本偵測結果
• 目標版本建議
• 應執行的 codemods
• 可能需要手動調整的地方
• 驗證檢查清單

這樣在允許它實際修改前，你會更容易審查輸出內容。

我一定要先知道目標版本嗎？

不一定。你可以請 next-upgrade 先檢查 repo，並推薦最安全的目標版本。但如果你已經因平台限制或相依套件需求，明確知道需要某個版本，先把目標講清楚，通常會得到更乾淨的升級計畫。

什麼情況下不該用 next-upgrade？

以下情況建議略過 next-upgrade：

• 你是在建立新 app，而不是升級既有 app
• 你的問題與版本遷移無關
• 你的技術棧依賴官方文件未涵蓋的客製化內部實作
• 你只需要一條指令，而且已經清楚知道精確的版本升級路徑

next-upgrade 能處理跨多個版本的跳升嗎？

可以，但應該採用漸進式升級。這個技能明確偏好逐步升 major 版本，而不是一次盲跳。如果你的 app 已經落後很多版本，請要求它提供分階段計畫，並在每個 major 版本後設置檢查點。

它只適用於 app router 專案嗎？

不是，但它抓取的官方指南可能會更著重較新的 Next.js 慣例。如果你的程式碼庫仍使用較舊的模式，請先要求代理辨識哪些指南內容適用、哪些不適用，再開始修改。

如何改善 next-upgrade 技能的使用效果

先給 next-upgrade 更清楚的 repo 邊界

想提升結果品質，最快的方法就是明確告訴代理 Next.js app 在哪裡。在 monorepo 裡，請具體說明：

• app 路徑，例如 apps/web
• package manager
• workspace 工具
• 修改是否只限於該 app 內部

否則，這個技能可能會讀錯 package.json，或在錯誤的層級提出指令。

要求 next-upgrade 分兩階段輸出

一個很穩健的模式是：

1. 先規劃
2. 再執行修改

例如：

• Use next-upgrade to first produce an upgrade plan with required codemods and risks. After I approve it, apply the changes.

這樣可以降低不小心大範圍修改的風險，也會讓這個技能在 production codebase 上更值得信任。

提供更明確的驗證標準

不要只說「升級成功」。請要求代理用具體指令驗證，例如：

• install
• lint
• typecheck
• unit tests
• production build

這能改善 next-upgrade usage，因為代理會以「讓 repo 真正通過驗證」為目標，而不只是把相依版本號改掉。

直接說出你最在意的失敗風險

如果你最在意的是避免特定回歸，請直接講明。例如：

• Prioritize route behavior and middleware compatibility
• Watch for request API changes introduced in newer Next.js versions
• Do not migrate unrelated code while applying next-upgrade

這些限制條件，通常會比一句籠統的「讓它能跑」更能引導出高品質修改。

要求說明為什麼選這些 codemods

一個很實用的改善型 prompt 是：

• List which @next/codemod transforms apply to this repo and why before running them

這能幫助你確認代理是否真的有依照程式碼模式挑選 transforms，而不是不加判斷地把 codemods 全跑一遍。

next-upgrade 常見失敗模式

常見的低品質結果通常有這些特徵：

• 還沒確認目前版本就直接升級相依套件
• 跳過中間 major 版本
• 還沒檢查 codemods 就先手動改程式
• 忽略 react 與 react-dom 的版本對齊
• 在 monorepo 中誤把根目錄 package.json 當成 app 的 package 檔

如果你看到這些情況，先停下來，改要求它提供逐版本的升級計畫。

收到第一輪輸出後，next-upgrade 應該怎麼迭代

第一輪完成後，請根據真正失敗的地方，要求第二輪更聚焦的處理，例如：

• Re-run next-upgrade analysis based on these build errors
• Compare the remaining errors against the official v15 guide
• Propose the smallest manual edits still needed after codemods

這比從頭重來更好，因為這個技能本來就是圍繞 migration steps 設計的，不是追求一次就完美。

想得到更高品質結果時，最佳的 next-upgrade prompt 模式

一個精簡但高訊號的模板如下：

Use next-upgrade on <path>. Detect the current Next.js version from package.json, determine the correct incremental upgrade path to <target-version>, fetch the official migration guides for each step, identify and run the applicable @next/codemod transforms first, then update next/react/react-dom together. After edits, summarize breaking changes addressed, remaining manual follow-ups, and the exact verification commands I should run.

這個 prompt 能給 next-upgrade skill 足夠的結構，讓它產出的內容明顯優於一般的 Code Editing 請求。