Turbopack

Turbopack 是一個增量打包器，專為 JavaScript 和 TypeScript 最佳化，用 Rust 編寫，並內置於 Next.js 中。您可以將 Turbopack 與 Pages 和 App Router 配合使用，以獲得更快的本地開發體驗。

為何選擇 Turbopack？

我們構建 Turbopack 是為了提升 Next.js 的效能，其中包括

• 統一圖： Next.js 支援多種輸出環境（例如，客戶端和伺服器）。管理多個編譯器並將包縫合在一起可能很繁瑣。Turbopack 為所有環境使用單個統一圖。
• 打包與原生 ESM： 有些工具在開發中跳過打包，並依賴瀏覽器的原生 ESM。這對於小型應用程式很有效，但由於過多的網路請求，可能會減慢大型應用程式的速度。Turbopack 在開發中打包，但以最佳化方式保持大型應用程式的快速。
• 增量計算： Turbopack 在多個核心之間並行工作，並將結果快取到函式級別。一旦完成一項工作，Turbopack 不會重複它。
• 懶惰打包： Turbopack 只打包開發伺服器實際請求的內容。這種懶惰方法可以減少初始編譯時間和記憶體使用。

開始使用

Turbopack 現在是 Next.js 中的預設打包器。使用 Turbopack 無需配置

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

使用 Webpack 而不是 Turbopack

如果需要使用 Webpack 而不是 Turbopack，可以使用 --webpack 標誌進行選擇

{
  "scripts": {
    "dev": "next dev --webpack",
    "build": "next build --webpack",
    "start": "next start"
  }
}

支援的功能

Next.js 中的 Turbopack 對於常見用例是零配置的。以下是開箱即用支援的功能摘要，以及在需要時如何進一步配置 Turbopack 的一些參考。

語言功能

框架和 React 功能

CSS 和樣式

資產

模組解析

效能和快速重新整理

與 webpack 的已知差距

在遷移應用程式時，webpack 和 Turbopack 之間存在許多重要的行為差異，需要注意。通常，這些對於新應用程式來說不是問題。

CSS 模組排序

Turbopack 將遵循 JS 匯入順序來排序未指定順序的CSS 模組。例如

import utilStyles from './utils.module.css'
import buttonStyles from './button.module.css'
export default function BlogPost() {
  return (
    <div className={utilStyles.container}>
      <button className={buttonStyles.primary}>Click me</button>
    </div>
  )
}

在此示例中，Turbopack 將確保 utils.module.css 將在生成的 CSS 塊中出現在 button.module.css 之前，遵循匯入順序

Webpack 通常也會這樣做，但在某些情況下它會忽略 JS 推斷的順序，例如它推斷 JS 檔案是無副作用的。

如果應用程式依賴任意排序，這可能會在採用 Turbopack 時導致細微的渲染變化。通常，解決方案很簡單，例如讓 button.module.css @import utils.module.css 以強制排序，或者識別衝突的規則並更改它們以不針對相同的屬性。

Sass node_modules 匯入

Turbopack 開箱即用支援匯入 node_modules Sass 檔案。Webpack 支援舊版波浪號 ~ 語法，Turbopack 不支援。

從

@import '~bootstrap/dist/css/bootstrap.min.css';

到

@import 'bootstrap/dist/css/bootstrap.min.css';

如果無法更新匯入，可以新增 turbopack.resolveAlias 配置將 ~ 語法對映到實際路徑

module.exports = {
  turbopack: {
    resolveAlias: {
      '~*': '*',
    },
  },
}

包大小

根據我們對生產應用程式的測試，我們觀察到 Turbopack 生成的包大小通常與 Webpack 相似。然而，比較可能很困難，因為 turbopack 傾向於生成更少但更大的塊。我們的建議是關注更高層次的指標，例如核心 Web 生命體徵或您自己的應用程式級指標來比較兩種打包器的效能。然而，我們確實意識到一個可能偶爾導致大規模迴歸的差距。

Turbopack 尚未擁有 webpack 中預設啟用的內部圖最佳化的等效功能。此最佳化對於搖樹大型模組很有用。例如

import heavy from 'some-heavy-dependency.js'
 
export function usesHeavy() {
  return heavy.run()
}
 
export const CONSTANT_VALUE = 3

如果應用程式只使用 CONSTANT_VALUE，Turbopack 將檢測到這一點並刪除 usesHeavy 匯出，但不會刪除相應的 import。然而，透過內部圖最佳化，webpack 也可以刪除 import，這也可以刪除依賴項。

我們計劃在 Turbopack 中提供等效的內部圖最佳化，但仍在開發中。如果您受到此差距的影響，請考慮手動拆分模組。

構建快取

Webpack 支援磁碟構建快取以提高構建效能。Turbopack 提供了類似的選擇加入功能，目前處於測試階段。從 Next 16 開始，您可以透過設定以下實驗性標誌來啟用 Turbopack 的檔案系統快取

• experimental.turbopackFileSystemCacheForDev
• experimental.turbopackFileSystemCacheForBuild

須知： 因此，在比較 webpack 和 Turbopack 效能時，請務必在構建之間刪除 .next 資料夾以進行公平比較，或啟用 turbopack 檔案系統快取功能。

Webpack 外掛

Turbopack 不支援 webpack 外掛。這會影響依賴 webpack 外掛系統進行整合的第三方工具。我們確實支援webpack 載入器。如果您依賴 webpack 外掛，則需要找到相容 Turbopack 的替代方案，或者繼續使用 webpack，直到提供等效功能。

不支援和未計劃的功能

某些功能尚未實現或未計劃

• 舊版 CSS Modules 功能
  • 獨立的 :local 和 :global 偽類（僅支援函式變體 :global(...)）。
  • @value 規則（已被 CSS 變數取代）。
  • :import 和 :export ICSS 規則。
  • .module.css 中的 composes 組合 .css 檔案。在 webpack 中，這將把 .css 檔案視為 CSS 模組，而對於 Turbopack，.css 檔案將始終是全域性的。這意味著如果要在 CSS 模組中使用 composes，需要將 .css 檔案更改為 .module.css 檔案。
  • CSS Modules 中的 @import 匯入 .css 作為 CSS 模組。在 webpack 中，這將把 .css 檔案視為 CSS 模組，而對於 Turbopack，.css 檔案將始終是全域性的。這意味著如果要在 CSS 模組中使用 @import，需要將 .css 檔案更改為 .module.css 檔案。
• sassOptions.functions 不支援在 sassOptions.functions 中定義的自定義 Sass 函式。此功能允許定義可在編譯期間從 Sass 程式碼呼叫的 JavaScript 函式。Turbopack 基於 Rust 的架構無法直接執行透過 sassOptions.functions 傳遞的 JavaScript 函式，這與完全在 JavaScript 中執行的 webpack 基於 Node.js 的 sass-loader 不同。如果您正在使用自定義 Sass 函式，則需要使用 webpack 而不是 Turbopack。
• webpack() 配置 在 next.config.js 中 Turbopack 取代了 webpack，因此不識別 webpack() 配置。請改用turbopack 配置。
• Yarn PnP 不計劃在 Next.js 中支援 Turbopack。
• experimental.urlImports 不計劃用於 Turbopack。
• experimental.esmExternals 不計劃。Turbopack 不支援 Next.js 中的舊版 esmExternals 配置。
• 一些 Next.js 實驗性標誌
  • experimental.nextScriptWorkers
  • experimental.sri.algorithm
  • experimental.fallbackNodePolyfills 我們計劃將來實現這些功能。

有關每個功能標誌及其狀態的完整詳細分類，請參閱Turbopack API 參考。

配置

Turbopack 可以透過 next.config.js（或 next.config.ts）在 turbopack 鍵下進行配置。配置選項包括

• rules 定義用於檔案轉換的額外webpack 載入器。
• resolveAlias 建立手動別名（類似於 webpack 中的 resolve.alias）。
• resolveExtensions 更改或擴充套件模組解析的副檔名。

module.exports = {
  turbopack: {
    // Example: adding an alias and custom file extension
    resolveAlias: {
      underscore: 'lodash',
    },
    resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.json'],
  },
}

有關更深入的配置示例，請參閱Turbopack 配置文件。

生成跟蹤檔案以進行效能除錯

如果您遇到效能或記憶體問題並希望幫助 Next.js 團隊診斷它們，可以透過在開發命令後附加 NEXT_TURBOPACK_TRACING=1 來生成跟蹤檔案

NEXT_TURBOPACK_TRACING=1 next dev

這將生成一個 .next/dev/trace-turbopack 檔案。在 Next.js 儲存庫上建立 GitHub issue 時，請包含此檔案，以幫助我們進行調查。

預設情況下，開發伺服器輸出到 .next/dev。閱讀有關isolatedDevBuild的更多資訊。

總結

Turbopack 是一個基於 Rust 的增量打包器，旨在使本地開發和構建變得快速——特別是對於大型應用程式。它整合到 Next.js 中，提供零配置的 CSS、React 和 TypeScript 支援。

版本變更