跳到内容

Turbopack

Turbopack 是一款增量式打包器,针对 JavaScript 和 TypeScript 进行了优化,使用 Rust 编写,并内置于 Next.js 中。你可以将 Turbopack 与 Pages 和 App Router 一起使用,以获得更快的本地开发体验。

为什么选择 Turbopack?

我们构建 Turbopack 是为了提升 Next.js 的性能,包括:

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

开始使用

要在你的 Next.js 项目中启用 Turbopack,请将 --turbopack 标志添加到你的 package.json 文件中的 devbuildstart 脚本中

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

目前,用于 dev 的 Turbopack 是稳定的,而 build 仍处于 alpha 阶段。我们正在积极开发生产环境支持,随着 Turbopack 越来越接近稳定。

支持的功能

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

语言特性

功能状态备注
JavaScript & TypeScript已支持底层使用 SWC。类型检查不由 Turbopack 完成(运行 tsc --watch 或依赖你的 IDE 进行类型检查)。
ECMAScript (ESNext)已支持Turbopack 支持最新的 ECMAScript 功能,与 SWC 的覆盖范围一致。
CommonJS已支持开箱即用地处理 require() 语法。
ESM已支持完全支持静态和动态 import
Babel部分不支持Turbopack 默认不包含 Babel。但是,你可以通过 Turbopack 配置配置 babel-loader

框架和 React 特性

功能状态备注
JSX / TSX已支持SWC 处理 JSX/TSX 编译。
快速刷新已支持无需配置。
React 服务器组件 (RSC)已支持用于 Next.js App Router。Turbopack 确保正确的服务器/客户端捆绑。
根布局创建不支持不支持在 App Router 中自动创建根布局。Turbopack 将指导你手动创建它。

CSS 和样式

功能状态备注
全局 CSS已支持直接在你的应用程序中导入 .css 文件。
CSS 模块已支持.module.css 文件原生工作(Lightning CSS)。
CSS 嵌套已支持Lightning CSS 支持现代 CSS 嵌套
@import 语法已支持合并多个 CSS 文件。
PostCSS已支持自动处理 Node.js 工作池中的 postcss.config.js。对 Tailwind、Autoprefixer 等很有用。
Sass / SCSS已支持 (Next.js)对于 Next.js,Sass 开箱即用。在未来,Turbopack 独立使用可能需要加载器配置。
Less计划通过插件实现默认情况下尚不支持。一旦自定义加载器稳定,可能需要加载器配置。
Lightning CSS正在使用处理 CSS 转换。一些低使用率的 CSS 模块功能(如 :local/:global 作为独立的伪类)尚不支持。请参阅下文了解更多详情。

资源

功能状态备注
静态资源(图像、字体)已支持导入 import img from './img.png' 开箱即用。在 Next.js 中,为 <Image /> 组件返回一个对象。
JSON 导入已支持支持从 .json 进行命名或默认导入。

模块解析

功能状态备注
路径别名已支持读取 tsconfig.jsonpathsbaseUrl,与 Next.js 行为匹配。
手动别名已支持next.config.js 中配置 resolveAlias(类似于 webpack.resolve.alias)。
自定义扩展名已支持next.config.js 中配置 resolveExtensions.
AMD部分支持基本转换有效;高级 AMD 用法受到限制。

性能和快速刷新

功能状态备注
快速刷新已支持无需完全刷新即可更新 JavaScript、TypeScript 和 CSS。
增量捆绑已支持Turbopack 仅延迟构建开发服务器请求的内容,从而加快大型应用程序的速度。

不支持和未计划的功能

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

  • 传统 CSS 模块功能
    • 独立的 :local:global 伪类(仅支持函数变体 :global(...))。
    • @value 规则(已被 CSS 变量取代)。
    • :import:export ICSS 规则。
  • webpack() 配置next.config.js 中。Turbopack 替换了 webpack,因此无法识别 webpack() 配置。请改用 experimental.turbo 配置
  • 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 在开发和未来的生产构建中启用或禁用 tree shaking。
  • memoryLimit 设置 Turbopack 的内存限制(以字节为单位)。
next.config.js
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 附加到你的 dev 命令来生成跟踪文件

NEXT_TURBOPACK_TRACING=1 next dev --turbopack

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

总结

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

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

版本变更

版本变更
v15.3.0build 的实验性支持
v15.0.0用于 dev 的 Turbopack 稳定版