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

Turbopack 现在是 Next.js 中的默认打包工具。使用 Turbopack 无需任何配置：

¥Turbopack is now the default bundler in Next.js. No configuration is needed to use Turbopack:

改用 Webpack ​

¥Using Webpack instead

如果你需要使用 Webpack 而不是 Turbopack，可以使用 --webpack 标志启用：

¥If you need to use Webpack instead of Turbopack, you can opt-in with the --webpack flag:

支持的功能 ​

¥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支持从 Next.js 16 开始，如果 Turbopack 检测到 配置文件，则会自动使用 Babel。与 webpack 不同，SWC 始终用于 Next.js 的内部转换以及降级到较旧的 ECMAScript 版本。如果存在 Babel 配置文件，使用 webpack 的 Next.js 会禁用 SWC（动态内容缓存）。除非你使用 手动配置 babel-loader，否则 node_modules 中的文件将被排除。

框架和 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。自定义 Sass 函数 (sassOptions.functions) 不受支持，因为 Turbopack 基于 Rust 的架构无法像 webpack 的 Node.js 环境那样直接执行 JavaScript 函数。如果需要此功能，请使用 Webpack。将来，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.

文件系统根目录 ​

¥Filesystem Root

Turbopack 使用根目录来解析模块。项目根目录之外的文件不会被解析。

¥Turbopack uses the root directory to resolve modules. Files outside of the project root are not resolved.

例如，当链接项目根目录之外的依赖（通过 npm link、yarn link、pnpm link 等）时，默认情况下这些链接的文件将不会被解析。要解析这些文件，你必须将根选项配置为项目及其链接依赖的父目录。

¥For example, when linking dependencies outside the project root (via npm link, yarn link, pnpm link, etc.), those linked files will not be resolved by default. To resolve these files, you must configure the root option to the parent directory of both the project and the linked dependencies.

你可以使用 next.config.js 中的 turbopack.root 选项配置文件系统根目录。

¥You can configure the filesystem root using turbopack.root option in next.config.js.

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.

Sass node_modules 导入 ​

¥Sass node_modules imports

Turbopack 开箱即用，支持导入 node_modules Sass 文件。Webpack 支持传统的波浪号 ~ 语法，而 Turbopack 不支持。

¥Turbopack supports importing node_modules Sass files out of the box. Webpack supports a legacy tilde ~ syntax for this, which is not supported by Turbopack.

来自：

¥From:

scss
@import '~bootstrap/dist/css/bootstrap.min.css';

至：

¥To:

scss
@import 'bootstrap/dist/css/bootstrap.min.css';

如果你无法更新导入，则可以添加 turbopack.resolveAlias 配置，将 ~ 语法映射到实际路径：

¥If you can't update the imports, you can add a turbopack.resolveAlias configuration to map the ~ syntax to the actual path:

构建缓存 ​

¥Build Caching

Webpack 支持 磁盘构建缓存 以提升构建性能。Turbopack 提供类似的功能，目前处于 beta 测试阶段。从 Next.js 16 开始，你可以通过设置以下实验性标志来启用 Turbopack 的文件系统缓存：

¥Webpack supports disk build caching to improve build performance. Turbopack provides a similar feature, currently in beta. Starting with Next 16, you can enable Turbopack’s filesystem cache by setting the following experimental flags:

需要了解：因此，在比较 webpack 和 Turbopack 的性能时，请确保在构建之间删除 .next 文件夹，以便进行公平的冷构建比较；或者启用 Turbopack 文件系统缓存功能，以便比较热构建。

¥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 cold build comparison or enable the turbopack filesystem cache feature to compare warm builds.

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.

  • sassOptions.functions 在 sassOptions.functions 中定义的自定义 Sass 函数不受支持。此功能允许定义可在编译期间从 Sass 代码调用的 JavaScript 函数。与完全在 JavaScript 中运行的 webpack 基于 Node.js 的 sass-loader 不同，Turbopack 基于 Rust 的架构无法直接执行通过 sassOptions.functions 传递的 JavaScript 函数。如果你使用自定义 Sass 函数，则需要使用 webpack 而不是 Turbopack。

    ¥sassOptions.functions Custom Sass functions defined in sassOptions.functions are not supported. This feature allows defining JavaScript functions that can be called from Sass code during compilation. Turbopack's Rust-based architecture cannot directly execute JavaScript functions passed through sassOptions.functions, unlike webpack's Node.js-based sass-loader which runs entirely in JavaScript. If you're using custom Sass functions, you'll need to use webpack instead of Turbopack.

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

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

有关更深入的配置示例，请参阅 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

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

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

默认情况下，开发服务器输出到 .next/dev。阅读有关 isolatedDevBuild 的更多信息。

¥By default the development server outputs to .next/dev. Read more about isolatedDevBuild.

摘要 ​

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

版本变更 ​

¥Version Changes

版本更改
v16.0.0Turbopack 成为 Next.js 的默认打包工具。找到配置文件时自动支持 Babel。
v15.5.0Turbopack 支持 build beta 版
v15.3.0对 build 的实验性支持
v15.0.0dev 稳定版的 Turbopack