Menu

Turbopack

Turbopack 是一个用 Rust 编写的专为 JavaScript 和 TypeScript 优化的增量打包工具,并内置于 Next.js 中。

使用方法

Turbopack 可以在 Next.js 的 pagesapp 目录中使用,以实现更快的本地开发。要启用 Turbopack,在运行 Next.js 开发服务器时使用 --turbopack 标志。

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

支持的功能

Next.js 中的 Turbopack 对大多数用户来说无需配置,并且可以扩展以适应更高级的使用场景。要了解更多关于 Turbopack 当前支持的功能,请查看 API 参考

不支持的功能

Turbopack 目前仅支持 next dev 而不支持 next build。我们正在努力实现构建支持,以便向稳定版本迈进。

以下功能目前不支持:

  • Turbopack 使用 Lightning CSS,它不支持一些使用率较低的 CSS Modules 功能
    • 作为独立伪类的 :local:global。仅支持函数变体,例如::global(a)
    • 已被 CSS 变量取代的 @value 规则。
    • :import:export ICSS 规则。
  • 无效的 CSS 注释语法,如 //
    • CSS 注释应按规范写作 /* comment */
    • 预处理器如 Sass 支持这种替代注释语法。
  • webpack()next.config.js 中的配置
  • Babel (.babelrc)
    • Turbopack 使用 SWC 编译器进行所有转译和优化。这意味着默认不包含 Babel。
    • 如果你有 .babelrc 文件,你可能不再需要它,因为 Next.js 将常用的 Babel 插件作为可启用的 SWC 转换包含在内。你可以在编译器文档中了解更多信息。
    • 如果在验证你的特定用例未被覆盖后仍需要使用 Babel,你可以利用 Turbopack 的自定义 webpack 加载器支持来包含 babel-loader
  • 在 App Router 中自动创建根布局。
    • 由于这会更改输入文件,目前不支持此行为,而是会显示错误提示你在所需位置手动添加根布局。
  • @next/font(旧版字体支持)。
    • @next/font 已被弃用,推荐使用 next/fontnext/font 在 Turbopack 中完全支持。
  • Relay 转换
    • 我们计划在未来实现这一功能。
  • pages/_document.tsx 中阻止 .css 导入
    • 目前在 webpack 中,Next.js 会阻止在 pages/_document.tsx 中导入 .css 文件
    • 我们计划在未来实现这个警告。
  • experimental.typedRoutes
    • 我们计划在未来实现这一功能。
  • experimental.nextScriptWorkers
    • 我们计划在未来实现这一功能。
  • experimental.sri.algorithm
    • 我们计划在未来实现这一功能。
  • experimental.fallbackNodePolyfills
    • 我们计划在未来实现这一功能。
  • experimental.esmExternals
    • 我们目前不计划在 Turbopack 的 Next.js 中支持旧版的 esmExternals 配置。
  • AMP
    • 我们目前不计划在 Turbopack 的 Next.js 中支持 AMP。
  • Yarn PnP
    • 我们目前不计划在 Turbopack 的 Next.js 中支持 Yarn PnP。
  • experimental.urlImports
    • 我们目前不计划在 Turbopack 的 Next.js 中支持 experimental.urlImports
  • :import:export ICSS 规则
    • 由于 Turbopack 使用的 CSS 解析器 Lightning CSS 不支持这些规则,我们目前不计划在 Turbopack 的 Next.js 中支持 :import:export ICSS 规则。
  • edge 运行时中的 unstable_allowDynamic 配置

生成跟踪文件

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

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