turbopack 选项允许您自定义 Turbopack，以转换不同的文件并更改模块的解析方式。

须知：turbopack 选项在 Next.js 13.0.0 到 15.2.x 版本中曾名为 experimental.turbo。experimental.turbo 选项将在 Next.js 16 中移除。

如果您使用的是较旧的 Next.js 版本，请运行 npx @next/codemod@latest next-experimental-turbo-to-turbopack . 以自动迁移您的配置。

import type { NextConfig } from 'next'

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

export default nextConfig

/** @type {import('next').NextConfig} */
const nextConfig = {
  turbopack: {
    // ...
  },
}

module.exports = nextConfig

须知：

• Next.js 的 Turbopack 不需要为内置功能配置加载器。Turbopack 内置支持 CSS 和编译现代 JavaScript，因此如果您使用 @babel/preset-env，则无需 css-loader、postcss-loader 或 babel-loader。

参考

选项

turbopack 配置支持以下选项：

支持的加载器

以下加载器已通过测试，可与 Turbopack 的 webpack 加载器实现配合使用，但即使此处未列出，许多其他 webpack 加载器也应能正常工作：

• babel-loader （如果找到 Babel 配置文件，则自动配置）
• @svgr/webpack
• svg-inline-loader
• yaml-loader
• string-replace-loader
• raw-loader
• sass-loader （自动配置）
• graphql-tag/loader

缺失的 Webpack 加载器特性

Turbopack 使用 loader-runner 库来执行 webpack 加载器，该库提供了大部分标准加载器 API。然而，某些特性尚不支持：

模块加载：

• importModule - 不支持
• loadModule - 不支持

文件系统和输出：

• fs - 部分支持：目前仅实现了 fs.readFile。
• emitFile - 不支持

上下文属性：

• version - 不支持
• mode - 不支持
• target - 不支持

实用工具：

• utils - 不支持
• resolve - 不支持（请改用 getResolve）

如果您有一个加载器严重依赖于这些特性之一，请提交一个 issue。

示例

根目录

Turbopack 使用根目录来解析模块。项目根目录之外的文件将不被解析。

文件不被解析到项目根目录之外的原因是为了改进缓存验证，减少文件系统监视开销，并减少所需的解析步骤数量。

Next.js 会自动检测您项目的根目录。它通过查找以下文件之一来完成此操作：

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

如果您有不同的项目结构，例如您不使用工作区，则可以手动设置 root 选项：

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

要解析项目根目录之外的链接依赖项（通过 npm link、yarn link、pnpm link 等）中的文件，您必须将 turbopack.root 配置为项目和链接依赖项的父目录。

虽然这会扩大文件系统监视的范围，但通常只在开发期间，当您积极处理链接包时才需要这样做。

配置 webpack 加载器

如果您需要内置功能之外的加载器支持，许多 webpack 加载器已经可以与 Turbopack 配合使用。目前存在一些限制：

• 仅实现了 webpack 加载器 API 的核心子集。目前，已涵盖一些流行的加载器，我们将来会扩展 API 支持。
• 仅支持返回 JavaScript 代码的加载器。目前不支持转换样式表或图像等文件的加载器。
• 传递给 webpack 加载器的选项必须是纯 JavaScript 原语、对象和数组。例如，不能将 require() 插件模块作为选项值传递。

要配置加载器，请在 next.config.js 中添加您已安装的加载器名称和任何选项，将文件扩展名映射到加载器列表。规则按顺序评估。

以下是使用 @svgr/webpack 加载器的示例，它允许导入 .svg 文件并将其渲染为 React 组件。

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

须知：rules 对象中使用的 glob 匹配基于文件名，除非 glob 包含 / 字符，这将导致它基于完整的项目相对文件路径进行匹配。Windows 文件路径会被规范化为使用 Unix 风格的 / 路径分隔符。

Turbopack 使用 Rust globset 库 的修改版本。

对于需要配置选项的加载器，您可以使用对象格式而不是字符串：

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

须知：在 Next.js 13.4.4 版本之前，turbopack.rules 被命名为 turbo.loaders，并且只接受像 .mdx 这样的文件扩展名而不是 *.mdx。

高级 webpack 加载器条件

您可以使用高级 condition 语法进一步限制加载器的运行位置：

module.exports = {
  turbopack: {
    rules: {
      // '*' will match all file paths, but we restrict where our
      // rule runs with a condition.
      '*': {
        condition: {
          all: [
            // 'foreign' is a built-in condition.
            { not: 'foreign' },
            // 'path' can be a RegExp or a glob string. A RegExp matches
            // anywhere in the full project-relative file path.
            { path: /^img\/[0-9]{3}\// },
            {
              any: [
                { path: '*.svg' },
                // 'content' is always a RegExp, and can match
                // anywhere in the file.
                { content: /\<svg\W/ },
              ],
            },
          ],
        },
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}

• 支持的布尔运算符是 {all: [...]}、{any: [...]} 和 {not: ...}。
• 支持的可自定义运算符是 {path: string | RegExp} 和 {content: RegExp}。如果 path 和 content 在同一个对象中指定，则它作为一个隐式 and 运行。

此外，还支持一些内置条件：

• browser：匹配将在客户端执行的代码。服务器端代码可以使用 {not: 'browser'} 进行匹配。
• foreign：匹配 node_modules 中的代码，以及一些 Next.js 内部代码。通常您会希望将加载器限制为 {not: 'foreign'}。这可以通过减少加载器调用的文件数量来提高性能。
• development：在使用 next dev 时匹配。
• production：在使用 next build 时匹配。
• node：匹配将在默认 Node.js 运行时上运行的代码。
• edge-light：匹配将在 Edge 运行时 上运行的代码。

规则可以是一个对象或一个对象数组。数组通常用于建模不相交的条件：

module.exports = {
  turbopack: {
    rules: {
      '*.svg': [
        {
          condition: 'browser',
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
        {
          condition: { not: 'browser' },
          loaders: [require.resolve('./custom-svg-loader.js')],
          as: '*.js',
        },
      ],
    },
  },
}

须知：所有匹配的规则都按顺序执行。

解析别名

Turbopack 可以配置为通过别名修改模块解析，类似于 webpack 的 resolve.alias 配置。

要配置解析别名，请在 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 字段：

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

这会用提供的列表覆盖原始的解析扩展名。请确保包含默认扩展名。

有关如何将您的应用程序从 webpack 迁移到 Turbopack 的更多信息和指导，请参阅 Turbopack 关于 webpack 兼容性的文档。

调试 ID

Turbopack 可以配置为在 JavaScript 包和源映射中生成 调试 ID。

要配置调试 ID，请在 next.config.js 中使用 debugIds 字段：

module.exports = {
  turbopack: {
    debugIds: true,
  },
}

此选项会自动将调试 ID 的 polyfill 添加到 JavaScript 包中，以确保兼容性。调试 ID 可通过 globalThis._debugIds 全局变量访问。

版本历史