turbopack

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

¥The turbopack option lets you customize Turbopack to transform different files and change how modules are resolved.

需要了解：在 Next.js 13.0.0 至 15.2.x 版本中，turbopack 选项之前名为 experimental.turbo。experimental.turbo 选项将在 Next.js 16 中被移除。

¥Good to know: The turbopack option was previously named experimental.turbo in Next.js versions 13.0.0 to 15.2.x. The experimental.turbo option will be removed in Next.js 16.

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

¥If you are using an older version of Next.js, run npx @next/codemod@latest next-experimental-turbo-to-turbopack . to automatically migrate your configuration.

import type { NextConfig } from 'next'

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

export default nextConfig

需要了解：

¥Good to know:

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

  ¥Turbopack for Next.js does not require loaders or loader configuration for built-in functionality. Turbopack has built-in support for CSS and compiling modern JavaScript, so there's no need for css-loader, postcss-loader, or babel-loader if you're using @babel/preset-env.

参考

¥Reference

选项

¥Options

turbopack 配置有以下选项：

¥The following options are available for the turbopack configuration:

选项	描述
root	设置应用根目录。应为绝对路径。
rules	使用 Turbopack 运行时要应用的受支持 webpack 加载器列表。
resolveAlias	将别名导入映射到模块以加载到其位置。
resolveExtensions	导入文件时要解析的扩展列表。
debugIds	在 JavaScript 包和源映射中启用 调试 ID 的生成。

支持的加载器

¥Supported loaders

以下加载器已测试可与 Turbopack 的 webpack 加载器实现兼容，但即使此处未列出，许多其他 webpack 加载器也应该可以正常工作：

¥The following loaders have been tested to work with Turbopack's webpack loader implementation, but many other webpack loaders should work as well even if not listed here:

• babel-loader （如果找到 Babel 配置文件，则自动配置）

  ¥babel-loader (Configured automatically if a Babel configuration file is found)

• @svgr/webpack

• svg-inline-loader

• yaml-loader

• string-replace-loader

• raw-loader

• sass-loader （自动配置）

  ¥sass-loader (Configured automatically)

• graphql-tag/loader

缺少 Webpack 加载器功能

¥Missing Webpack loader features

Turbopack 使用 loader-runner 库来执行 webpack 加载器，该库提供了大部分标准加载器 API。但是，某些功能不受支持：

¥Turbopack uses the loader-runner library to execute webpack loaders, which provides most of the standard loader API. However, some features are not supported:

模块加载：

¥Module loading:

• importModule - 不支持

  ¥importModule - No support

• loadModule - 不支持

  ¥loadModule - No support

文件系统和输出：

¥File system and output:

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

  ¥fs - Partial support: only fs.readFile is currently implemented.

• emitFile - 不支持

  ¥emitFile - No support

上下文属性：

¥Context properties:

• version - 不支持

  ¥version - No support

• mode - 不支持

  ¥mode - No support

• target - 不支持

  ¥target - No support

实用工具：

¥Utilities:

• utils - 不支持

  ¥utils - No support

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

  ¥resolve - No support (use getResolve instead)

如果你的加载器严重依赖于这些功能之一，请提交问题报告。

¥If you have a loader that is critically dependent upon one of these features please file an issue.

示例

¥Examples

根目录

¥Root directory

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

¥Turbopack uses the root directory to resolve modules. Files outside of the project root are not resolved.

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

¥The reason files are not resolved outside of the project root is to improve cache validation, reduce filesystem watching overhead, and reduce the number of resolving steps needed.

Next.js 会自动检测项目的根目录。它通过查找以下文件之一来实现：

¥Next.js automatically detects the root directory of your project. It does so by looking for one of these files:

• pnpm-lock.yaml

• package-lock.json

• yarn.lock

• bun.lock

• bun.lockb

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

¥If you have a different project structure, for example if you don't use workspaces, you can manually set the root option:

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

¥To resolve files from linked dependencies outside the project root (via npm link, yarn link, pnpm link, etc.), you must configure the turbopack.root to the parent directory of both the project and the linked dependencies.

虽然这扩展了文件系统监视的范围，但通常只有在开发过程中积极处理链接包时才需要这样做。

¥While this expands the scope of filesystem watching, it's typically only necessary during development when actively working on linked packages.

配置 webpack 加载器

¥Configuring webpack loaders

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

¥If you need loader support beyond what's built in, many webpack loaders already work with Turbopack. There are currently some limitations:

• 仅实现了 webpack 加载器 API 的核心子集。目前，对于一些流行的加载器已经有足够的覆盖，我们将在未来扩展我们的 API 支持。

  ¥Only a core subset of the webpack loader API is implemented. Currently, there is enough coverage for some popular loaders, and we'll expand our API support in the future.

• 仅支持返回 JavaScript 代码的加载器。目前不支持转换样式表或图片等文件的加载器。

  ¥Only loaders that return JavaScript code are supported. Loaders that transform files like stylesheets or images are not currently supported.

• 传递给 webpack 加载器的选项必须是纯 JavaScript 原语、对象和数组。例如，无法将 require() 插件模块作为选项值传递。

  ¥Options passed to webpack loaders must be plain JavaScript primitives, objects, and arrays. For example, it's not possible to pass require() plugin modules as option values.

要配置加载器，请在 next.config.js 中添加已安装加载器的名称及其所有选项，并将文件扩展名映射到加载器列表。规则按顺序执行。

¥To configure loaders, add the names of the loaders you've installed and any options in next.config.js, mapping file extensions to a list of loaders. Rules are evaluated in order.

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

¥Here is an example below using the @svgr/webpack loader, which enables importing .svg files and rendering them as React components.

需要了解：rules 对象中使用的 glob 模式基于文件名进行匹配，除非 glob 模式包含 / 字符，此时将基于完整的项目相对文件路径进行匹配。Windows 文件路径会被规范化，使用 Unix 风格的 / 路径分隔符。

¥Good to know: Globs used in the rules object match based on file name, unless the glob contains a / character, which will cause it to match based on the full project-relative file path. Windows file paths are normalized to use unix-style / path separators.

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

¥Turbopack uses a modified version of the Rust globset library.

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

¥For loaders that require configuration options, you can use an object format instead of a string:

需要了解：在 Next.js 版本 13.4.4 之前，turbopack.rules 被命名为 turbo.loaders，并且仅接受 .mdx 等文件扩展名，而不接受 *.mdx。

¥Good to know: Prior to Next.js version 13.4.4, turbopack.rules was named turbo.loaders and only accepted file extensions like .mdx instead of *.mdx.

高级 webpack 加载器条件

¥Advanced webpack loader conditions

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

¥You can further restrict where a loader runs using the advanced condition syntax:

• 支持的布尔运算符为 {all: [...]}、{any: [...]} 和 {not: ...}。

  ¥Supported boolean operators are {all: [...]}, {any: [...]} and {not: ...}.

• 支持的可自定义运算符为 {path: string | RegExp} 和 {content: RegExp}。如果在同一个对象中指定了 path 和 content，则该对象会隐式地充当 and。

  ¥Supported customizable operators are {path: string | RegExp} and {content: RegExp}. If path and content are specified in the same object, it acts as an implicit and.

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

¥In addition, a number of built-in conditions are supported:

• browser：匹配将在客户端执行的代码。可以使用 {not: 'browser'} 匹配服务器代码。

  ¥browser: Matches code that will execute on the client. Server code can be matched using {not: 'browser'}.

• foreign：匹配 node_modules 中的代码以及一些 Next.js 内部代码。通常，你需要将加载器限制在 {not: 'foreign'} 中。这可以通过减少加载器调用的文件数量来提高性能。

  ¥foreign: Matches code in node_modules, as well as some Next.js internals. Usually you'll want to restrict loaders to {not: 'foreign'}. This can improve performance by reducing the number of files the loader is invoked on.

• development：使用 next dev 时匹配。

  ¥development: Matches when using next dev.

• production：使用 next build 时匹配。

  ¥production: Matches when using next build.

• node：匹配将在默认 Node.js 运行时上运行的代码。

  ¥node: Matches code that will run on the default Node.js runtime.

• edge-light：匹配将在 边缘运行时 上运行的代码。

  ¥edge-light: Matches code that will run on the Edge runtime.

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

¥Rules can be an object or an array of objects. An array is often useful for modeling disjoint conditions:

需要了解：所有匹配规则按顺序执行。

¥Good to know: All matching rules are executed in order.

解析别名

¥Resolving aliases

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

¥Turbopack can be configured to modify module resolution through aliases, similar to webpack's resolve.alias configuration.

要配置解析别名，请将导入的模式映射到 next.config.js 中的新目标：

¥To configure resolve aliases, map imported patterns to their new destination in next.config.js:

这会将 underscore 包的导入别名为 lodash 包。换句话说，import underscore from 'underscore' 将加载 lodash 模块而不是 underscore。

¥This aliases imports of the underscore package to the lodash package. In other words, import underscore from 'underscore' will load the lodash module instead of underscore.

Turbopack 还支持通过此字段进行条件别名，类似于 Node.js 的 条件导出。目前仅支持 browser 条件。在上述情况下，当 Turbopack 面向浏览器环境时，mocha 模块的导入将被别名为 mocha/browser-entry.js。

¥Turbopack also supports conditional aliasing through this field, similar to Node.js' conditional exports. At the moment only the browser condition is supported. In the case above, imports of the mocha module will be aliased to mocha/browser-entry.js when Turbopack targets browser environments.

解析自定义扩展

¥Resolving custom extensions

Turbopack 可以配置为使用自定义扩展来解析模块，类似于 webpack 的 resolve.extensions 配置。

¥Turbopack can be configured to resolve modules with custom extensions, similar to webpack's resolve.extensions configuration.

要配置解析扩展，请使用 next.config.js 中的 resolveExtensions 字段：

¥To configure resolve extensions, use the resolveExtensions field in next.config.js:

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

¥This overwrites the original resolve extensions with the provided list. Make sure to include the default extensions.

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

¥For more information and guidance for how to migrate your app to Turbopack from webpack, see Turbopack's documentation on webpack compatibility.

调试 ID

¥Debug IDs

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

¥Turbopack can be configured to generate debug IDs in JavaScript bundles and source maps.

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

¥To configure debug IDs, use the debugIds field in next.config.js:

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

¥The option automatically adds a polyfill for debug IDs to the JavaScript bundle to ensure compatibility. The debug IDs are available in the globalThis._debugIds global variable.

版本历史

¥Version History

版本	更改
16.0.0	turbopack.debugIds 已添加。
16.0.0	turbopack.rules.*.condition 已添加。
15.3.0	experimental.turbo 已更改为 turbopack。
13.0.0	experimental.turbo 已引入。