Turbopack 是一个针对 JavaScript 和 TypeScript 优化的增量打包器，用 Rust 编写并内置于 Next.js 中。您可以在 Pages 路由和 App 路由中都使用 Turbopack，以获得更快的本地开发体验。

为什么选择 Turbopack？

我们构建 Turbopack 旨在提升 Next.js 的性能，包括：

• 统一图谱： Next.js 支持多种输出环境（例如，客户端和服务器）。管理多个编译器并将捆绑包拼接在一起可能很繁琐。Turbopack 为所有环境使用单个统一图谱。
• 打包 vs 原生 ESM： 某些工具在开发中跳过打包，依赖浏览器的原生 ESM。这对于小型应用程序很有效，但由于过多的网络请求，可能会减慢大型应用程序的速度。Turbopack 在开发中进行打包，但以优化方式进行，以保持大型应用程序的快速运行。
• 增量计算： Turbopack 在多个核心之间并行化工作，并缓存结果到函数级别。一旦完成某项工作，Turbopack 不会重复执行。
• 惰性打包： Turbopack 仅打包开发服务器实际请求的内容。这种惰性方法可以减少初始编译时间和内存使用。

入门

Turbopack 现在是 Next.js 中的默认打包器。使用 Turbopack 无需配置：

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

转而使用 Webpack

如果您需要使用 Webpack 而非 Turbopack，可以通过 --webpack 标志选择启用：

{
  "scripts": {
    "dev": "next dev --webpack",
    "build": "next build --webpack",
    "start": "next start"
  }
}

支持的功能

Next.js 中的 Turbopack 对于常见用例是零配置的。以下是开箱即用支持的功能摘要，以及在需要时如何进一步配置 Turbopack 的一些参考。

语言特性

框架和 React 特性

CSS 和样式

资产

模块解析

性能和 Fast Refresh

与 webpack 的已知差距

webpack 和 Turbopack 之间存在许多重要的非微小行为差异，在迁移应用程序时需要注意。通常，对于新应用程序来说，这些问题较少。

文件系统根目录

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

例如，当链接项目根目录之外的依赖项（通过 npm link、yarn link、pnpm link 等）时，这些链接的文件默认不会被解析。要解析这些文件，您必须将 root 选项配置为项目和链接依赖项的父目录。

您可以使用 next.config.js 中的 turbopack.root 选项配置文件系统根目录。

CSS Module 排序

Turbopack 将遵循 JS 导入顺序来排列未以其他方式排序的 CSS modules。例如：

import utilStyles from './utils.module.css'
import buttonStyles from './button.module.css'
export default function BlogPost() {
  return (
    <div className={utilStyles.container}>
      <button className={buttonStyles.primary}>Click me</button>
    </div>
  )
}

在此示例中，Turbopack 将确保 utils.module.css 在生成的 CSS 块中出现在 button.module.css 之前，遵循导入顺序。

Webpack 通常也会这样做，但在某些情况下它会忽略 JS 推断的排序，例如，如果它推断 JS 文件没有副作用。

这可能会导致采用 Turbopack 时出现细微的渲染变化，如果应用程序依赖于任意排序。通常，解决方案很简单，例如让 button.module.css @import utils.module.css 以强制排序，或者识别冲突规则并将其更改为不针对相同的属性。

Sass node_modules 导入

Turbopack 开箱即用支持导入 node_modules 中的 Sass 文件。Webpack 支持一种旧版波浪号 ~ 语法，但 Turbopack 不支持。

从：

@import '~bootstrap/dist/css/bootstrap.min.css';

到：

@import 'bootstrap/dist/css/bootstrap.min.css';

如果您无法更新导入，可以添加 turbopack.resolveAlias 配置，将 ~ 语法映射到实际路径：

module.exports = {
  turbopack: {
    resolveAlias: {
      '~*': '*',
    },
  },
}

捆绑包大小

根据我们对生产应用程序的测试，我们观察到 Turbopack 生成的捆绑包大小通常与 Webpack 相似。然而，比较可能很困难，因为 turbopack 倾向于生成更少但更大的块。我们的建议是关注更高级别的指标，例如 Core Web Vitals 或您自己的应用程序级别指标来比较两个打包器之间的性能。但是，我们确实意识到一个可能偶尔导致大规模退步的差距。

Turbopack 尚未提供与 webpack 中默认启用的 Inner Graph Optimization 等效的功能。此优化对于摇树优化大型模块非常有用。例如：

import heavy from 'some-heavy-dependency.js'

export function usesHeavy() {
  return heavy.run()
}

export const CONSTANT_VALUE = 3

如果应用程序只使用 CONSTANT_VALUE，Turbopack 将检测到这一点并删除 usesHeavy 导出，但不会删除相应的 import。但是，通过 Inner Graph Optimization，webpack 也可以删除 import，这也可以删除依赖项。

我们计划在 Turbopack 中提供等效的 Inner Graph Optimization，但它仍在开发中。如果您受到此差距的影响，请考虑手动拆分模块。

构建缓存

Webpack 支持磁盘构建缓存以提高构建性能。Turbopack 提供了一个类似的选择加入功能，目前处于测试阶段。从 Next 16 开始，您可以通过设置以下实验性标志来启用 Turbopack 的文件系统缓存：

• experimental.turbopackFileSystemCacheForDev
• experimental.turbopackFileSystemCacheForBuild

须知： 因此，在比较 webpack 和 Turbopack 性能时，请确保在构建之间删除 .next 文件夹以进行公平比较，或者启用 turbopack 文件系统缓存功能。

Webpack 插件

Turbopack 不支持 webpack 插件。这会影响依赖 webpack 插件系统进行集成的第三方工具。我们支持 webpack loaders。如果您依赖 webpack 插件，您需要寻找 Turbopack 兼容的替代方案，或者继续使用 webpack，直到提供等效功能。

不支持和未计划的功能

有些功能尚未实现或未计划：

• 旧版 CSS Modules 功能
  • 独立的 :local 和 :global 伪类（仅支持函数变体 :global(...)）。
  • @value 规则（已被 CSS 变量取代）。
  • :import 和 :export ICSS 规则。
  • .module.css 中的 composes 复合一个 .css 文件。在 webpack 中，这会将 .css 文件视为 CSS Module，而在 Turbopack 中，.css 文件始终是全局的。这意味着如果您想在 CSS Module 中使用 composes，您需要将 .css 文件更改为 .module.css 文件。
  • CSS Modules 中 @import 导入 .css 作为 CSS Module。在 webpack 中，这会将 .css 文件视为 CSS Module，而在 Turbopack 中，.css 文件始终是全局的。这意味着如果您想在 CSS Module 中使用 @import，您需要将 .css 文件更改为 .module.css 文件。
• sassOptions.functions
  不支持在 sassOptions.functions 中定义的自定义 Sass 函数。此功能允许定义在编译期间可从 Sass 代码调用的 JavaScript 函数。Turbopack 基于 Rust 的架构无法直接执行通过 sassOptions.functions 传递的 JavaScript 函数，这与 webpack 基于 Node.js 的 sass-loader 完全在 JavaScript 中运行不同。如果您正在使用自定义 Sass 函数，则需要使用 webpack 而不是 Turbopack。
• next.config.js 中的 webpack() 配置
  Turbopack 取代了 webpack，因此不识别 webpack() 配置。请改用 turbopack 配置。
• Yarn PnP
  未计划在 Next.js 中支持 Turbopack。
• experimental.urlImports
  未计划用于 Turbopack。
• experimental.esmExternals
  未计划。Turbopack 不支持 Next.js 中的旧版 esmExternals 配置。
• 一些 Next.js 实验性标志
  • experimental.nextScriptWorkers
  • experimental.sri.algorithm
  • experimental.fallbackNodePolyfills
    我们计划将来实现这些功能。

有关每个功能标志及其状态的完整详细分类，请参阅 Turbopack API 参考。

配置

Turbopack 可以通过 next.config.js（或 next.config.ts）中的 turbopack 键进行配置。配置选项包括：

• rules
  定义用于文件转换的额外 webpack loaders。
• resolveAlias
  创建手动别名（类似于 webpack 中的 resolve.alias）。
• resolveExtensions
  更改或扩展模块解析的文件扩展名。

module.exports = {
  turbopack: {
    // Example: adding an alias and custom file extension
    resolveAlias: {
      underscore: 'lodash',
    },
    resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.json'],
  },
}

有关更深入的配置示例，请参阅 Turbopack 配置文档。

生成跟踪文件以进行性能调试

如果您遇到性能或内存问题，并希望帮助 Next.js 团队诊断它们，您可以通过在开发命令中添加 NEXT_TURBOPACK_TRACING=1 来生成跟踪文件：

NEXT_TURBOPACK_TRACING=1 next dev

这将生成一个 .next/dev/trace-turbopack 文件。在 Next.js 仓库 上创建 GitHub issue 时请附上该文件，以帮助我们进行调查。

默认情况下，开发服务器输出到 .next/dev。阅读更多关于 isolatedDevBuild 的信息。

总结

Turbopack 是一个 Rust-based、增量打包器，旨在使本地开发和构建快速——特别是对于大型应用程序。它集成在 Next.js 中，提供零配置的 CSS、React 和 TypeScript 支持。

版本变更