Turbopack

Turbopack 是一个专为 JavaScript 和 TypeScript 优化的 增量式打包工具，采用 Rust 编写，并内置于 Next.js。您可以在页面路由和应用路由器中使用 Turbopack，以获得 更快速 的本地开发体验。

为什么选择 Turbopack？

我们开发 Turbopack 是为了提升 Next.js 的性能，包括：

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

快速开始

要在您的 Next.js 项目中启用 Turbopack，请在 package.json 文件的 dev 和 build 脚本中添加 --turbopack 标志：

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

目前，Turbopack 的 dev 功能已稳定，而 build 功能处于 alpha 阶段。我们正在积极开发生产环境支持，Turbopack 正逐步趋于稳定。

支持的功能

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

语言功能

框架和 React 功能

CSS 和样式

资源

模块解析

性能和快速刷新

不支持和不计划支持的功能

某些功能尚未实现或不计划支持：

• 遗留 CSS 模块功能
  • 独立的 :local 和 :global 伪类（仅支持函数变体 :global(...)）。
  • @value 规则（由 CSS 变量取代）。
  • :import 和 :export ICSS 规则。
  • .module.css 中的 composes 组合 .css 文件。在 webpack 中会将 .css 文件视为 CSS 模块，而 Turbopack 始终将 .css 文件视为全局。这意味着如果要在 CSS 模块中使用 composes，需要将 .css 文件改为 .module.css 文件。
  • CSS 模块中的 @import 导入 .css 作为 CSS 模块。在 webpack 中会将 .css 文件视为 CSS 模块，而 Turbopack 始终将 .css 文件视为全局。这意味着如果要在 CSS 模块中使用 @import，需要将 .css 文件改为 .module.css 文件。
• next.config.js 中的 webpack() 配置 Turbopack 替代了 webpack，因此不识别 webpack() 配置。改用 turbopack 配置。
• AMP Next.js 中不计划支持 Turbopack。
• Yarn PnP Next.js 中不计划支持 Turbopack。
• experimental.urlImports 不计划支持 Turbopack。
• experimental.esmExternals 不计划支持。Turbopack 不支持 Next.js 中的遗留 esmExternals 配置。
• 部分 Next.js 实验性标志
  • experimental.typedRoutes
  • experimental.nextScriptWorkers
  • experimental.sri.algorithm
  • experimental.fallbackNodePolyfills 我们计划在未来实现这些功能。

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

配置

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

• rules 定义额外的 webpack 加载器 用于文件转换。
• resolveAlias 创建手动别名（类似于 webpack 中的 resolve.alias）。
• resolveExtensions 更改或扩展模块解析的文件扩展名。
• moduleIds 设置模块 ID 的生成方式（'named' 或 'deterministic'）。
• treeShaking 在开发和未来的生产构建中启用或禁用摇树优化。
• memoryLimit 设置 Turbopack 的内存限制（以字节为单位）。

module.exports = {
  turbopack: {
    // 示例：添加别名和自定义文件扩展名
    resolveAlias: {
      underscore: 'lodash',
    },
    resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.json'],
  },
}

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

生成性能调试跟踪文件

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

NEXT_TURBOPACK_TRACING=1 next dev --turbopack

这将生成 .next/trace-turbopack 文件。在 Next.js 仓库 创建 GitHub 问题时包含该文件，以帮助我们调查。

总结

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

随着我们继续改进 Turbopack 并添加生产构建支持，请关注更多更新。同时，尝试使用 next dev --turbopack 并告诉我们您的反馈。

版本变更