Turbopack

Turbopack 是一个增量打包器，专为 JavaScript 和 TypeScript 优化，用 Rust 编写，并内置于 Next.js 中。您可以将 Turbopack 与 Pages 和 App Router 配合使用，以获得更快的本地开发体验。

为何选择 Turbopack？

我们构建 Turbopack 是为了提升 Next.js 的性能，其中包括

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

开始使用

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

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

使用 Webpack 而不是 Turbopack

如果需要使用 Webpack 而不是 Turbopack，可以使用 --webpack 标志进行选择

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

支持的功能

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

语言功能

框架和 React 功能

CSS 和样式

资产

模块解析

性能和快速刷新

与 webpack 的已知差距

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

CSS 模块排序

Turbopack 将遵循 JS 导入顺序来排序未指定顺序的CSS 模块。例如

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 倾向于生成更少但更大的块。我们的建议是关注更高层次的指标，例如核心 Web 生命体征或您自己的应用程序级指标来比较两种打包器的性能。然而，我们确实意识到一个可能偶尔导致大规模回归的差距。

Turbopack 尚未拥有 webpack 中默认启用的内部图优化的等效功能。此优化对于摇树大型模块很有用。例如

import heavy from 'some-heavy-dependency.js'
 
export function usesHeavy() {
  return heavy.run()
}
 
export const CONSTANT_VALUE = 3

如果应用程序只使用 CONSTANT_VALUE，Turbopack 将检测到这一点并删除 usesHeavy 导出，但不会删除相应的 import。然而，通过内部图优化，webpack 也可以删除 import，这也可以删除依赖项。

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

构建缓存

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

• experimental.turbopackFileSystemCacheForDev
• experimental.turbopackFileSystemCacheForBuild

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

Webpack 插件

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

不支持和未计划的功能

某些功能尚未实现或未计划

• 旧版 CSS Modules 功能
  • 独立的 :local 和 :global 伪类（仅支持函数变体 :global(...)）。
  • @value 规则（已被 CSS 变量取代）。
  • :import 和 :export ICSS 规则。
  • .module.css 中的 composes 组合 .css 文件。在 webpack 中，这将把 .css 文件视为 CSS 模块，而对于 Turbopack，.css 文件将始终是全局的。这意味着如果要在 CSS 模块中使用 composes，需要将 .css 文件更改为 .module.css 文件。
  • CSS Modules 中的 @import 导入 .css 作为 CSS 模块。在 webpack 中，这将把 .css 文件视为 CSS 模块，而对于 Turbopack，.css 文件将始终是全局的。这意味着如果要在 CSS 模块中使用 @import，需要将 .css 文件更改为 .module.css 文件。
• sassOptions.functions 不支持在 sassOptions.functions 中定义的自定义 Sass 函数。此功能允许定义可在编译期间从 Sass 代码调用的 JavaScript 函数。Turbopack 基于 Rust 的架构无法直接执行通过 sassOptions.functions 传递的 JavaScript 函数，这与完全在 JavaScript 中运行的 webpack 基于 Node.js 的 sass-loader 不同。如果您正在使用自定义 Sass 函数，则需要使用 webpack 而不是 Turbopack。
• webpack() 配置 在 next.config.js 中 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 加载器。
• 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 的增量打包器，旨在使本地开发和构建变得快速——特别是对于大型应用程序。它集成到 Next.js 中，提供零配置的 CSS、React 和 TypeScript 支持。

版本变更