跳到主要内容

turbopack

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

next.config.ts
import type { NextConfig } from 'next'

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

export default nextConfig

提示：

  • Next.js 的 Turbopack 不需要为内置功能配置加载器或加载器配置。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

如果你有不同的项目结构，例如如果你不使用工作区，你可以手动设置 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.0experimental.turbo 更改为 turbopack。
13.0.0引入 experimental.turbo。
最后于 更新