跳到主要内容

Turbopack

Turbopack 是一个专为 JavaScript 和 TypeScript 优化的增量打包工具，用 Rust 编写，并内置到 Next.js 中。你可以在 Pages 和 App 路由中使用 Turbopack，获得更快的本地开发体验。

为什么选择 Turbopack？

我们构建 Turbopack 是为了推动 Next.js 的性能，包括：

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

开始使用

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

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

目前，Turbopack 的 dev 模式是稳定的，而 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 编译。 | | Fast Refresh | 支持 | 无需配置。 | | React Server Components (RSC) | 支持 | 适用于 Next.js App 路由。Turbopack 确保正确的服务器/客户端打包。 | | Root layout creation | 不支持 | App 路由中自动创建根布局不受支持。Turbopack 将指导你手动创建它。 |

CSS 和样式

| 功能 | 状态 | 说明 | | ------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Global CSS | 支持 | 直接在应用程序中导入 .css 文件。 | | CSS Modules | 支持 | .module.css 文件原生工作（Lightning CSS）。 | | CSS Nesting | 支持 | Lightning CSS 支持现代 CSS 嵌套。 | | @import syntax | 支持 | 组合多个 CSS 文件。 | | PostCSS | 支持 | 在 Node.js 工作池中自动处理 postcss.config.js。适用于 Tailwind、Autoprefixer 等。 | | Sass / SCSS | 支持 (Next.js) | 对于 Next.js，Sass 开箱即用。将来，Turbopack 独立使用可能需要加载器配置。 | | Less | 计划通过插件 | 默认尚不支持。一旦自定义加载器稳定，可能需要加载器配置。 | | Lightning CSS | 使用中 | 处理 CSS 转换。一些低使用率的 CSS Modules 功能（如独立的伪类 :local/:global）尚不支持。详见下文 |

资源

| 功能 | 状态 | 说明 | | --------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------- | | Static Assets (images, fonts) | 支持 | 导入 import img from './img.png' 开箱即用。在 Next.js 中，返回 <Image /> 组件的对象。 | | JSON Imports | 支持 | 支持从 .json 进行命名或默认导入。 |

模块解析

| 功能 | 状态 | 说明 | | --------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Path Aliases | 支持 | 读取 tsconfig.json 的 paths 和 baseUrl，匹配 Next.js 行为。 | | Manual Aliases | 支持 | 在 next.config.js 中配置 resolveAlias（类似于 webpack.resolve.alias）。 | | Custom Extensions | 支持 | 在 next.config.js 中配置 resolveExtensions。 | | AMD | 部分支持 | 基本转换有效；高级 AMD 使用受限。 |

性能和 Fast Refresh

| 功能 | 状态 | 说明 | | ------------------------ | ------------- | ---------------------------------------------------------------------------------------- | | Fast Refresh | 支持 | 更新 JavaScript、TypeScript 和 CSS，无需完全刷新。 | | Incremental Bundling | 支持 | Turbopack 懒加载构建开发服务器请求的内容，加速大型应用程序。 |

不支持和未计划的功能

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

  • 遗留 CSS Modules 功能
    • 独立的 :local 和 :global 伪类（仅支持函数变体 :global(...)）。
    • @value 规则（被 CSS 变量取代）。
    • :import 和 :export ICSS 规则。
    • 在 .module.css 中组合 .css 文件的 composes。在 webpack 中，这会将 .css 文件视为 CSS Module，而在 Turbopack 中，.css 文件始终是全局的。这意味着如果你想在 CSS Module 中使用 composes，需要将 .css 文件更改为 .module.css 文件。
    • 在 CSS Modules 中将 .css 作为 CSS Module 导入的 @import。在 webpack 中，这会将 .css 文件视为 CSS Module，而在 Turbopack 中，.css 文件始终是全局的。这意味着如果你想在 CSS Module 中使用 @import，需要将 .css 文件更改为 .module.css 文件。
  • webpack() 配置 在 next.config.js 中 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' vs 'deterministic'）。
  • treeShaking 在开发和未来的生产构建中启用或禁用 tree shaking。
  • memoryLimit 为 Turbopack 设置内存限制（以字节为单位）。
next.config.js
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 issue 时包含该文件，以帮助我们调查。

总结

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

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

版本更改

| 版本 | 更改 | | --------- | -------------------------------- | | v15.3.0 | build 的实验性支持 | | v15.0.0 | dev 的 Turbopack 稳定 |

最后于 更新