turbopack

turbopack 選項讓您可以自訂 Turbopack 來轉換不同檔案並改變模組解析方式。

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    // ...
  },
}

export default nextConfig

須知:

Next.js 的 Turbopack 不需要載入器 (loader) 或載入器設定來實現內建功能。Turbopack 內建支援 CSS 和現代 JavaScript 編譯，因此如果您使用 @babel/preset-env，就不需要 css-loader、postcss-loader 或 babel-loader。

參考

選項

以下選項可用於 turbo 設定：

選項	說明
`root`	設定應用程式根目錄。應為絕對路徑。
`rules`	執行 Turbopack 時要套用的支援 webpack 載入器清單。
`resolveAlias`	將別名導入映射到要載入的模組。
`resolveExtensions`	導入檔案時要解析的副檔名清單。

支援的載入器

以下載入器已測試可與 Turbopack 的 webpack 載入器實作相容，但許多其他 webpack 載入器即使未列出也應可運作：

範例

根目錄

Turbopack 使用根目錄來解析模組。專案根目錄外的檔案不會被解析。

Next.js 會自動偵測您專案的根目錄。它會尋找以下檔案之一：

pnpm-lock.yaml
package-lock.json
yarn.lock
bun.lock
bun.lockb

如果您有不同的專案結構，例如不使用工作區 (workspaces)，可以手動設定 root 選項：

next.config.js

const path = require('path')
module.exports = {
  turbopack: {
    root: path.join(__dirname, '..'),
  },
}

設定 webpack 載入器

如果您需要超出內建功能的載入器支援，許多 webpack 載入器已經可以與 Turbopack 一起使用。目前有一些限制：

僅實作了 webpack 載入器 API 的核心子集。目前已有足夠的覆蓋率支援一些熱門載入器，我們將在未來擴展 API 支援。
僅支援回傳 JavaScript 程式碼的載入器。目前不支援轉換樣式表或圖片等檔案的載入器。
傳遞給 webpack 載入器的選項必須是純 JavaScript 基本型別、物件和陣列。例如，無法將 require() 的插件模組作為選項值傳遞。

要設定載入器，請在 next.config.js 中新增您已安裝的載入器名稱和任何選項，將副檔名映射到載入器清單。

以下範例使用 @svgr/webpack 載入器，該載入器允許導入 .svg 檔案並將其渲染為 React 元件。

next.config.js

module.exports = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}

對於需要設定選項的載入器，您可以使用物件格式而非字串：

next.config.js

module.exports = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: [
          {
            loader: '@svgr/webpack',
            options: {
              icon: true,
            },
          },
        ],
        as: '*.js',
      },
    },
  },
}

須知：在 Next.js 13.4.4 版之前，turbo.rules 名為 turbo.loaders，且僅接受像 .mdx 這樣的副檔名而非 *.mdx。

解析別名

可以設定 Turbopack 透過別名修改模組解析，類似於 webpack 的 resolve.alias 設定。

要設定解析別名，請在 next.config.js 中將導入模式映射到其新目的地：

next.config.js

module.exports = {
  turbopack: {
    resolveAlias: {
      underscore: 'lodash',
      mocha: { browser: 'mocha/browser-entry.js' },
    },
  },
}

這會將 underscore 套件的導入別名為 lodash 套件。換句話說，import underscore from 'underscore' 將載入 lodash 模組而非 underscore。

Turbopack 也透過此欄位支援條件式別名，類似於 Node.js 的條件式導出。目前僅支援 browser 條件。在上面的例子中，當 Turbopack 目標為瀏覽器環境時，mocha 模組的導入將被別名為 mocha/browser-entry.js。

解析自訂副檔名

可以設定 Turbopack 解析具有自訂副檔名的模組，類似於 webpack 的 resolve.extensions 設定。

要設定解析副檔名，請在 next.config.js 中使用 resolveExtensions 欄位：

next.config.js

module.exports = {
  turbopack: {
    resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.json'],
  },
}

這會以提供的清單覆寫原始解析副檔名。請確保包含預設副檔名。

有關如何從 webpack 遷移應用程式到 Turbopack 的更多資訊和指南，請參閱 Turbopack 關於 webpack 相容性的文件。

版本歷史

版本	變更
`15.3.0`	`experimental.turbo` 變更為 `turbopack`。
`13.0.0`	引入 `experimental.turbo`。

On this page