跳到内容

turbo

此功能目前处于实验阶段,可能会发生变化,不建议用于生产环境。试用并分享您在 GitHub 上的反馈。

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-loaderpostcss-loaderbabel-loader

参考

选项

以下选项可用于 turbo 配置

选项描述
root设置应用程序根目录。应为绝对路径。
rules使用 Turbopack 运行时要应用的受支持 webpack 加载器列表。
resolveAlias将别名导入映射到要加载的模块。
resolveExtensions导入文件时要解析的扩展名列表。

支持的加载器

以下加载器已经过测试,可以与 Turbopack 的 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.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