Turbopack

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

¥Turbopack is an incremental bundler optimized for JavaScript and TypeScript, written in Rust, and built into Next.js. You can use Turbopack with both the Pages and App Router for a much faster local development experience.

为什么选择 Turbopack？

¥Why Turbopack?

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

¥We built Turbopack to push the performance of Next.js, including:

• 统一图表：Next.js 支持多种输出环境（例如，客户端和服务器）。管理多个编译器并将 bundles 拼接在一起可能非常繁琐。Turbopack 在所有环境中使用单一、统一的图形。

  ¥Unified Graph: Next.js supports multiple output environments (e.g., client and server). Managing multiple compilers and stitching bundles together can be tedious. Turbopack uses a single, unified graph for all environments.

• 打包 vs 原生 ESM：某些工具在开发过程中会跳过打包，而依赖于浏览器的原生 ESM。这适用于小型应用，但由于网络请求过多，可能会降低大型应用的运行速度。Turbopack 在开发环境中进行打包，但会以优化的方式确保大型应用快速运行。

  ¥Bundling vs Native ESM: Some tools skip bundling in development and rely on the browser's native ESM. This works well for small apps but can slow down large apps due to excessive network requests. Turbopack bundles in dev, but in an optimized way to keep large apps fast.

• 增量计算：Turbopack 跨核心并行工作，并将结果缓存到函数级别。Turbopack 完成一项工作后，将不会重复执行。

  ¥Incremental Computation: Turbopack parallelizes work across cores and caches results down to the function level. Once a piece of work is done, Turbopack won’t repeat it.

• 延迟打包：Turbopack 仅打包开发服务器实际请求的内容。这种惰性方法可以减少初始编译时间和内存使用量。

  ¥Lazy Bundling: Turbopack only bundles what is actually requested by the dev server. This lazy approach can reduce initial compile times and memory usage.

入门

¥Getting started

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

¥To enable Turbopack in your Next.js project, add the --turbopack flag to the dev and build scripts in your package.json file:

目前，dev 的 Turbopack 已稳定，而 build 处于 alpha 阶段。随着 Turbopack 逐渐稳定，我们正在积极致力于生产支持。

¥Currently, Turbopack for dev is stable, while build is in alpha. We are actively working on production support as Turbopack moves closer to stability.

支持的功能

¥Supported features

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

¥Turbopack in Next.js has zero-configuration for the common use cases. Below is a summary of what is supported out of the box, plus some references to how you can configure Turbopack further when needed.

语言特性

¥Language features

功能	状态	注意
JavaScript 和 TypeScript	支持	在后台使用 SWC。Turbopack 不进行类型检查（运行 tsc --watch 或依赖你的 IDE 进行类型检查）。
ECMAScript (ESNext)	支持	Turbopack 支持最新的 ECMAScript 特性，与 SWC 的覆盖范围一致。
CommonJS	支持	require() 语法开箱即用。
ESM	支持	完全支持静态和动态 import。
Babel	部分不支持	Turbopack 默认不包含 Babel。但是，你可以使用 通过 Turbopack 配置配置 babel-loader。

框架和 React 功能

¥Framework and React features

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

CSS 和样式

¥CSS and styling

功能	状态	注意
全局 CSS	支持	直接在你的应用中导入 .css 文件。
CSS 模块	支持	.module.css 文件原生支持（Lightning CSS）。
CSS 嵌套	支持	Lightning CSS 支持 现代 CSS 嵌套。
@import syntax	支持	合并多个 CSS 文件。
PostCSS	支持	在 Node.js 工作池中自动处理 postcss.config.js。适用于 Tailwind、Autoprefixer 等。
Sass / SCSS	支持（Next.js）	Next.js 开箱即用地支持 Sass。将来，Turbopack 独立使用可能需要加载器配置。
更少	计划通过插件支持	默认情况下尚不支持。自定义加载器稳定后，可能需要加载器配置。
Lightning CSS	正在使用	处理 CSS 转换。一些使用率较低的 CSS 模块功能（例如作为独立伪类的 :local/:global）尚不受支持。更多详情，请参见下文。

资源

¥Assets

功能	状态	注意
静态资源（图片、字体）	支持	导入 import img from './img.png' 开箱即用。在 Next.js 中，返回 <Image /> 组件的对象。
JSON 导入	支持	支持从 .json 导入命名或默认内容。

模块解析

¥Module resolution

功能	状态	注意
路径别名	支持	读取 tsconfig.json 的 paths 和 baseUrl，与 Next.js 行为一致。
手动别名	支持	在 next.config.js 中配置 resolveAlias（类似于 webpack.resolve.alias）。
自定义扩展	支持	在 next.config.js 中配置 resolveExtensions。
AMD	部分支持	基本转换功能正常；高级 AMD 使用受限。

性能和快速刷新

¥Performance and Fast Refresh

功能	状态	注意
快速刷新	支持	无需完全刷新即可更新 JavaScript、TypeScript 和 CSS。
增量打包	支持	Turbopack 会延迟构建开发服务器请求的内容，从而加快大型应用的运行速度。

不支持和未计划的功能

¥Unsupported and unplanned features

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

¥Some features are not yet implemented or not planned:

• 旧版 CSS 模块功能

  ¥Legacy CSS Modules features

  • 独立的 :local 和 :global 伪类（仅支持函数变体 :global(...)）。

    ¥Standalone :local and :global pseudo-classes (only the function variant :global(...) is supported).

  • @value 规则（已被 CSS 变量取代）。

    ¥The @value rule (superseded by CSS variables).

  • :import 和 :export ICSS 规则。

    ¥:import and :export ICSS rules.

  • composes 在 .module.css 中编写 .css 文件。在 webpack 中，这会将 .css 文件视为 CSS 模块，而使用 Turbopack，.css 文件将始终是全局的。这意味着如果你想在 CSS 模块中使用 composes，则需要将 .css 文件更改为 .module.css 文件。

    ¥composes in .module.css composing a .css file. In webpack this would treat the .css file as a CSS Module, with Turbopack the .css file will always be global. This means that if you want to use composes in a CSS Module, you need to change the .css file to a .module.css file.

  • @import 在 CSS 模块中导入 .css 作为 CSS 模块。在 webpack 中，这会将 .css 文件视为 CSS 模块，而使用 Turbopack，.css 文件将始终是全局的。这意味着如果你想在 CSS 模块中使用 @import，则需要将 .css 文件更改为 .module.css 文件。

    ¥@import in CSS Modules importing .css as a CSS Module. In webpack this would treat the .css file as a CSS Module, with Turbopack the .css file will always be global. This means that if you want to use @import in a CSS Module, you need to change the .css file to a .module.css file.

• next.config.js Turbopack 中的 webpack() 配置取代了 webpack，因此无法识别 webpack() 配置。请改用 turbopack 配置。

  ¥webpack() configuration in next.config.js Turbopack replaces webpack, so webpack() configs are not recognized. Use the turbopack config instead.

• Next.js 中尚未计划支持 Turbopack。

  ¥AMP Not planned for Turbopack support in Next.js.

• Yarn PnP 尚未计划在 Next.js 中支持 Turbopack。

  ¥Yarn PnP Not planned for Turbopack support in Next.js.

• experimental.urlImports Turbopack 暂无计划支持。

  ¥experimental.urlImports Not planned for Turbopack.

• experimental.esmExternals 暂无计划。Turbopack 不支持 Next.js 中旧版 esmExternals 配置。

  ¥experimental.esmExternals Not planned. Turbopack does not support the legacy esmExternals configuration in Next.js.

• 一些 Next.js 实验性标志

  ¥Some Next.js Experimental Flags

  • experimental.typedRoutes

  • experimental.nextScriptWorkers

  • experimental.sri.algorithm

  • experimental.fallbackNodePolyfills 我们计划在未来实现这些功能。

    ¥experimental.fallbackNodePolyfills We plan to implement these in the future.

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

¥For a full, detailed breakdown of each feature flag and its status, see the Turbopack API Reference.

配置

¥Configuration

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

¥Turbopack can be configured via next.config.js (or next.config.ts) under the turbopack key. Configuration options include:

• rules 定义额外的 webpack 加载器 用于文件转换。

  ¥rules Define additional webpack loaders for file transformations.

• resolveAlias 创建手动别名（例如 webpack 中的 resolve.alias）。

  ¥resolveAlias Create manual aliases (like resolve.alias in webpack).

• resolveExtensions 更改或扩展文件扩展名以进行模块解析。

  ¥resolveExtensions Change or extend file extensions for module resolution.

• moduleIds 设置模块 ID 的生成方式（'named' 与 'deterministic'）。

  ¥moduleIds Set how module IDs are generated ('named' vs 'deterministic').

• treeShaking 在开发版本和未来的生产版本中启用或禁用 tree shake。

  ¥treeShaking Enable or disable tree shaking in dev and future production builds.

• memoryLimit 为 Turbopack 设置内存限制（以字节为单位）。

  ¥memoryLimit Set a memory limit (in bytes) for Turbopack.

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

¥For more in-depth configuration examples, see the Turbopack config documentation.

生成用于性能调试的跟踪文件

¥Generating trace files for performance debugging

如果你遇到性能或内存问题，并希望帮助 Next.js 团队进行诊断，可以将 NEXT_TURBOPACK_TRACING=1 附加到你的 dev 命令中来生成跟踪文件：

¥If you encounter performance or memory issues and want to help the Next.js team diagnose them, you can generate a trace file by appending NEXT_TURBOPACK_TRACING=1 to your dev command:

NEXT_TURBOPACK_TRACING=1 next dev --turbopack

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

¥This will produce a .next/trace-turbopack file. Include that file when creating a GitHub issue on the Next.js repo to help us investigate.

摘要

¥Summary

Turbopack 是一个基于 Rust 的增量打包器，旨在加快本地开发和构建速度，尤其适用于大型应用。它集成到 Next.js 中，提供零配置 CSS、React 和 TypeScript 支持。

¥Turbopack is a Rust-based, incremental bundler designed to make local development and builds fast—especially for large applications. It is integrated into Next.js, offering zero-config CSS, React, and TypeScript support.

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

¥Stay tuned for more updates as we continue to improve Turbopack and add production build support. In the meantime, give it a try with next dev --turbopack and let us know your feedback.

版本变更

¥Version Changes

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