Next.js 中文网

主题

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 会延迟构建开发服务器请求的内容，从而加快大型应用的运行速度。

Webpack 的已知缺陷 ​

¥Known gaps with webpack

webpack 和 Turbopack 之间存在一些重要的行为差异，在迁移应用时务必注意这些差异。通常，对于新应用来说，这些不太重要。

¥There are a number of non-trivial behavior differences between webpack and Turbopack that are important to be aware of when migrating an application. Generally, these are less of a concern for new applications.

CSS 模块排序 ​

¥CSS Module Ordering

Turbopack 将遵循 JS 导入顺序对未按其他顺序排列的 CSS 模块 进行排序。例如：

¥Turbopack will follow JS import order to order CSS modules which are not otherwise ordered. For example:

在此示例中，Turbopack 将确保 utils.module.css 在生成的 CSS 块中按照导入顺序出现在 button.module.css 之前。

¥In this example, Turbopack will ensure that utils.module.css will appear before button.module.css in the produced CSS chunk, following the import order

Webpack 通常也会这样做，但在某些情况下它会忽略 JS 推断的排序，例如，如果它推断 JS 文件没有副作用。

¥Webpack generally does this as well, but there are cases where it will ignore JS inferred ordering, for example if it infers the JS file is side-effect-free.

如果应用依赖于任意排序，则在采用 Turbopack 时，这可能会导致渲染发生细微的变化。通常，解决方案很简单，例如，使用 button.module.css @import utils.module.css 强制排序，或者识别冲突的规则并将其更改为不针对相同的属性。

¥This can lead to subtle rendering changes when adopting Turbopack, if applications have come to rely on an arbitrary ordering. Generally, the solution is easy, e.g. have button.module.css @import utils.module.css to force the ordering, or identify the conflicting rules and change them to not target the same properties.

Bundle 大小 ​

¥Bundle Sizes

Turbopack 在 webpack 中尚未提供与 内部图优化 等效的插件。此优化对于对大型模块进行摇树优化非常有用。例如：

¥Turbopack does not yet have an equivalent to the Inner Graph Optimization in webpack. This optimization is useful to tree shake large modules. For example:

如果应用仅使用 CONSTANT_VALUE，Turbopack 会检测到这一点并删除 usesHeavy 导出，但不会删除相应的 import。但是，启用 optimization.innerGraph = true 选项后，webpack 也可以删除 import。

¥If an application only uses CONSTANT_VALUE Turbopack will detect this and delete the usesHeavy export but not the corresponding import. However, with the optimization.innerGraph = true option enabled, webpack can delete the import too.

我们计划在 Turbopack 中提供与 innerGraph 优化等效的功能，但目前仍在开发中。如果你受到此差距的影响，请考虑手动拆分这些模块。

¥We are planning to offer an equivalent to the innerGraph optimization in Turbopack but it is still under development. If you are affected by this gap, consider manually splitting these modules.

构建缓存 ​

¥Build Caching

Webpack 支持 磁盘构建缓存 以加速构建。我们计划在 Turbopack 中支持类似的功能，但尚未准备就绪。在 next@canary 版本中，你可以通过启用 experimental.turbopackPersistentCaching flag 来试验我们的解决方案。

¥Webpack supports disk build caching to speed up builds. We are planning to support an analogous feature in Turbopack but it is not ready yet. On the next@canary release you can experiment with our solution by enabling the experimental.turbopackPersistentCaching flag.

需要了解：因此，在比较 webpack 和 Turbopack 性能时，请确保在构建之间删除 .next 文件夹，以确保公平的比较。

¥Good to know: For this reason, when comparing webpack and Turbopack performance, make sure to delete the .next folder between builds to see a fair comparison.

Webpack 插件 ​

¥Webpack plugins

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

¥Turbopack does not support webpack plugins. This affects third-party tools that rely on webpack's plugin system for integration. We do support webpack loaders. If you depend on webpack plugins, you'll need to find Turbopack-compatible alternatives or continue using webpack until equivalent functionality is available.

不支持和未计划的功能 ​

¥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.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').

  • 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:

bash
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.5.0Turbopack 支持 build beta 版
v15.3.0对 build 的实验性支持
v15.0.0dev 稳定版的 Turbopack