跳到主要内容

Turbopack

Turbopack 是一个针对 JavaScript 和 TypeScript 优化的增量打包器，用 Rust 编写，并内置于 Next.js 中。Turbopack 可在 pages 和 app 目录中的 Next.js 中使用，以加快本地开发速度。

¥Turbopack is an incremental bundler optimized for JavaScript and TypeScript, written in Rust, and built into Next.js. Turbopack can be used in Next.js in both the pages and app directories for faster local development.

要启用 Turbopack，请在运行 Next.js 开发服务器时使用 --turbopack 标志。

¥To enable Turbopack, use the --turbopack flag when running the Next.js development server.

{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}

参考​

¥Reference

支持的功能​

¥Supported features

Next.js 中的 Turbopack 需要大多数用户进行零配置，并且可以针对更高级的用例进行扩展。要了解有关 Turbopack 当前支持的功能的更多信息，请查看 API 参考。

¥Turbopack in Next.js requires zero-configuration for most users and can be extended for more advanced use cases. To learn more about the currently supported features for Turbopack, view the API Reference.

不支持的功能​

¥Unsupported features

Turbopack 目前仅支持 next dev，不支持 next build。随着我们越来越接近稳定，我们目前正在努力提供对构建的支持。

¥Turbopack currently only supports next dev and does not support next build. We are currently working on support for builds as we move closer towards stability.

目前不支持这些功能：

¥These features are currently not supported:

  • Turbopack 利用 Lightning CSS，它不支持一些使用率较低的 CSS 模块功能

    ¥Turbopack leverages Lightning CSS which doesn't support some low usage CSS Modules features

    • :local 和 :global 作为独立的伪类。仅支持函数变体，例如：:global(a)。

      ¥:local and :global as standalone pseudo classes. Only the function variant is supported, for example: :global(a).

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

      ¥The @value rule which has been superseded by CSS variables.

    • :import 和 :export ICSS 规则。

      ¥:import and :export ICSS rules.

  • 无效的 CSS 注释语法 如 //

    ¥Invalid CSS comment syntax such as //

    • CSS 注释应按照规范写为 /* comment */。

      ¥CSS comments should be written as /* comment */ per the specification.

    • Sass 等预处理器确实支持这种替代注释语法。

      ¥Preprocessors such as Sass do support this alternative syntax for comments.

  • next.config.js 中的 webpack() 配置

    ¥webpack() configuration in next.config.js

    • Turbopack 取代了 Webpack，这意味着不支持 webpack 配置。

      ¥Turbopack replaces Webpack, this means that webpack configuration is not supported.

    • 要配置 Turbopack，请参阅文档。

      ¥To configure Turbopack, see the documentation.

    • Turbopack 支持 Webpack 加载器 的子集。

      ¥A subset of Webpack loaders are supported in Turbopack.

  • Babel (.babelrc)

    • Turbopack 利用 SWC 编译器进行所有转译和优化。这意味着默认情况下不包含 Babel。

      ¥Turbopack leverages the SWC compiler for all transpilation and optimizations. This means that Babel is not included by default.

    • 如果你有 .babelrc 文件，你可能不再需要它，因为 Next.js 包含常见的 Babel 插件作为可以启用的 SWC 转换。你可以在 编译器文档 中阅读更多相关内容。

      ¥If you have a .babelrc file, you might no longer need it because Next.js includes common Babel plugins as SWC transforms that can be enabled. You can read more about this in the compiler documentation.

    • 如果在验证你的特定用例未涵盖后仍然需要使用 Babel，你可以利用 Turbopack 的 支持自定义 webpack 加载器 来包含 babel-loader。

      ¥If you still need to use Babel after verifying your particular use case is not covered, you can leverage Turbopack's support for custom webpack loaders to include babel-loader.

  • 在 App Router 中自动创建根布局。

    ¥Creating a root layout automatically in App Router.

    • 目前不支持此行为，因为它会更改输入文件，而是会显示错误，让你手动在所需位置添加根布局。

      ¥This behavior is currently not supported since it changes input files, instead, an error will be shown for you to manually add a root layout in the desired location.

  • @next/font（旧字体支持）。

    ¥@next/font (legacy font support).

    • @next/font 已被弃用，取而代之的是 next/font。Turbopack 完全支持 next/font。

      ¥@next/font is deprecated in favor of next/font. next/font is fully supported with Turbopack.

  • 继电器变换

    ¥Relay transforms

    • 我们计划在未来实现这一点。

      ¥We are planning to implement this in the future.

  • 在 pages/_document.tsx 中阻止 .css 导入

    ¥Blocking .css imports in pages/_document.tsx

    • 目前，使用 webpack Next.js 阻止在 pages/_document.tsx 中导入 .css 文件

      ¥Currently with webpack Next.js blocks importing .css files in pages/_document.tsx

    • 我们计划在未来实现此警告。

      ¥We are planning to implement this warning in the future.

  • experimental.typedRoutes

    • 我们计划在未来实现这一点。

      ¥We are planning to implement this in the future.

  • experimental.nextScriptWorkers

    • 我们计划在未来实现这一点。

      ¥We are planning to implement this in the future.

  • experimental.sri.algorithm

    • 我们计划在未来实现这一点。

      ¥We are planning to implement this in the future.

  • experimental.fallbackNodePolyfills

    • 我们计划在未来实现这一点。

      ¥We are planning to implement this in the future.

  • experimental.esmExternals

    • 我们目前不打算在 Next.js 中使用 Turbopack 支持旧版 esmExternals 配置。

      ¥We are currently not planning to support the legacy esmExternals configuration in Next.js with Turbopack.

  • AMP。

    • 我们目前不打算通过 Turbopack 在 Next.js 中支持 AMP。

      ¥We are currently not planning to support AMP in Next.js with Turbopack.

  • Yarn 即插即用

    ¥Yarn PnP

    • 我们目前不打算通过 Turbopack 在 Next.js 中支持 Yarn PnP。

      ¥We are currently not planning to support Yarn PnP in Next.js with Turbopack.

  • experimental.urlImports

    • 我们目前不打算通过 Turbopack 在 Next.js 中支持 experimental.urlImports。

      ¥We are currently not planning to support experimental.urlImports in Next.js with Turbopack.

  • :import 和 :export ICSS 规则

    ¥:import and :export ICSS rules

    • 我们目前不打算在 Next.js 中使用 Turbopack 支持 :import 和 :export ICSS 规则，因为 Turbopack 使用的 CSS 解析器 Lightning CSS 不支持这些规则。

      ¥We are currently not planning to support :import and :export ICSS rules in Next.js with Turbopack as Lightning CSS the CSS parser Turbopack uses does not support these rules.

  • Edge 运行时中的 unstable_allowDynamic 配置

    ¥unstable_allowDynamic configuration in edge runtime

示例​

¥Examples

生成跟踪文件​

¥Generating Trace Files

跟踪文件允许 Next.js 团队调查和改进性能指标和内存使用情况。要生成跟踪文件，请将 NEXT_TURBOPACK_TRACING=1 附加到 next dev --turbopack 命令，这将生成 .next/trace-turbopack 文件。

¥Trace files allow the Next.js team to investigate and improve performance metrics and memory usage. To generate a trace file, append NEXT_TURBOPACK_TRACING=1 to the next dev --turbopack command, this will generate a .next/trace-turbopack file.

报告与 Turbopack 性能和内存使用相关的问题时，请在 GitHub 问题中包含跟踪文件。

¥When reporting issues related to Turbopack performance and memory usage, please include the trace file in your GitHub issue.