nextjs-turbopack

Next.js 與 Turbopack

Next.js 16+ 預設使用 Turbopack 進行本地開發：這是一個以 Rust 撰寫的增量打包工具，能大幅提升開發啟動速度與熱更新效率。

使用時機

• Turbopack（預設開發模式）：日常開發使用。冷啟動與 HMR 更快，特別是在大型專案中。
• Webpack（舊版開發模式）：僅在遇到 Turbopack 錯誤或開發時依賴 webpack 專用外掛時使用。可透過 --webpack（或 --no-turbopack，取決於你的 Next.js 版本；請查閱對應版本的說明文件）停用 Turbopack。
• 正式環境：正式建置行為（next build）可能使用 Turbopack 或 webpack，取決於 Next.js 版本；請查閱官方 Next.js 文件以確認你的版本。

使用時機：開發或除錯 Next.js 16+ 應用程式、診斷開發啟動或 HMR 緩慢問題，或最佳化正式環境打包。

運作方式

• Turbopack：Next.js 開發用的增量打包工具。使用檔案系統快取，因此重新啟動速度更快（例如大型專案可提升 5–14 倍）。
• 開發模式預設：從 Next.js 16 開始，next dev 預設使用 Turbopack，除非手動停用。
• 檔案系統快取：重新啟動時會重複使用先前的工作；快取通常位於 .next 目錄下；基本使用無需額外設定。
• Bundle Analyzer（Next.js 16.1+）：實驗性的 Bundle Analyzer，可檢查輸出內容並找出大型相依套件；可透過設定或實驗性標記啟用（請參閱對應版本的 Next.js 文件）。

範例

指令

next dev
next build
next start

使用方式

執行 next dev 進行本地開發（使用 Turbopack）。使用 Bundle Analyzer（請參閱 Next.js 文件）最佳化程式碼分割並縮減大型相依套件。盡可能使用 App Router 與伺服器元件。

Middleware 檔案命名

Next.js 16 引入了 proxy.ts 作為 middleware 檔案名稱，取代舊有的 middleware.ts 慣例：

• Next.js 16+：在專案根目錄使用 proxy.ts
• Next.js 16 之前：在專案根目錄使用 middleware.ts

檔案名稱的變更與 Next.js 版本 有關，而非使用哪個打包工具（Turbopack 或 webpack）。請務必查閱你所檢視版本的官方文件。

請勿將 Next.js 16 專案中的 proxy.ts 標記為命名錯誤或缺少的 middleware 檔案。 該檔案是正確且有意為之。建議重新命名為 middleware.ts 將會導致 middleware 無法執行。

參考資料：Next.js proxy 文件

最佳實務

• 使用最新的 Next.js 16.x 版本以獲得穩定的 Turbopack 與快取行為。
• 如果開發速度緩慢，請確認你使用的是 Turbopack（預設）且快取未被不必要地清除。
• 針對正式環境打包大小問題，請使用對應版本的官方 Next.js 打包分析工具。