NNext.js 中文网 GitHub

Turbopack

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

Turbopack 是一个为 JavaScript 和 TypeScript 优化的增量打包器,使用 Rust 编写,并内置于 Next.js 中。你可以在 Pages Router 和 App Router 中使用 Turbopack,获得快得多的本地开发体验。

为什么选择 Turbopack?#

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

  • 统一的图(Graph): Next.js 支持多种输出环境(例如客户端和服务端)。管理多个编译器并将打包产物缝合在一起可能很繁琐。Turbopack 为所有环境使用单一、统一的图。
  • 打包 vs 原生 ESM: 一些工具在开发时跳过打包,依赖浏览器的原生 ESM。这对小应用效果很好,但由于过多的网络请求,可能会拖慢大型应用。Turbopack 在开发时进行打包,但以一种优化的方式保持大型应用的快速。
  • 增量计算: Turbopack 跨核心并行处理工作,并缓存到函数级别的结果。一项工作完成后,Turbopack 不会重复它。结果会在多次运行之间持久化到磁盘。
  • 惰性打包: Turbopack 只打包开发服务器实际请求的内容。这种惰性方式可以减少初始编译时间和内存占用。

支持的平台#

Turbopack 需要特定于平台的原生绑定。目前支持以下平台:

平台架构
macOS (Darwin)x64、ARM64
Windowsx64、ARM64
Linux (glibc)x64、ARM64
Linux (musl)x64、ARM64

在没有原生绑定的平台(例如 FreeBSD、OpenBSD)上,Next.js 会回退到 WebAssembly (WASM) 绑定。WASM 绑定支持核心 SWC 特性,如编译和压缩,但不支持 Turbopack。在这些平台上,请使用 --webpack 标志:

bash
next dev --webpack
next build --webpack

快速开始#

Turbopack 现在是 Next.js 中的默认打包器。无需任何配置即可使用 Turbopack:

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

改用 Webpack#

如果你需要使用 Webpack 而不是 Turbopack,可以通过 --webpack 标志选择加入:

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

支持的功能#

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

语言特性#

特性状态说明
JavaScript & TypeScript支持底层使用 SWC。类型检查不由 Turbopack 完成(运行 tsc --watch 或依赖你的 IDE 进行类型检查)。
ECMAScript (ESNext)支持Turbopack 支持最新的 ECMAScript 特性,与 SWC 的覆盖范围一致。
CommonJS支持开箱即用处理 require() 语法。
ESM支持完全支持静态和动态 import。
Babel支持从 Next.js 16 开始,如果检测到[配置文件][babel-config],Turbopack 会自动使用 Babel。与 webpack 不同,SWC 始终用于 Next.js 的内部转换和降级到较旧的 ECMAScript 版本。使用 webpack 的 Next.js 在存在 Babel 配置文件时会禁用 SWC。node_modules 中的文件被排除在外,除非你[手动配置 babel-loader][manual-loader]。

[babel-config]: https://s.nodejs.cn/7880b283-3786-4dd8-a86c-d8ff9feafeac [manual-loader]: /docs/app/api-reference/config/next-config-js/turbopack#configuring-webpack-loaders

框架和 React 特性#

特性状态说明
JSX / TSX支持SWC 处理 JSX/TSX 编译。
Fast Refresh支持无需配置。
React Server Components (RSC)支持适用于 Next.js App Router。Turbopack 确保正确的服务端/客户端打包。
根布局创建不支持不支持在 App Router 中自动创建根布局。Turbopack 会指示你手动创建。

CSS 和样式#

特性状态说明
全局 CSS支持在你的应用中直接导入 .css 文件。
CSS Modules支持.module.css 文件原生工作(Lightning CSS)。
CSS 嵌套支持Lightning CSS 支持现代 CSS 嵌套。
@import 语法支持合并多个 CSS 文件。
PostCSS支持在 Node.js worker 池中自动处理 PostCSS 配置文件(postcss.config.js、.mjs、.cjs、.ts、.mts、.cts)。对 Tailwind、Autoprefixer 等很有用。
Sass / SCSS支持(Next.js)对于 Next.js,Sass 开箱即用。不支持自定义 Sass 函数(sassOptions.functions),因为 Turbopack 基于 Rust 的架构无法直接执行 JavaScript 函数,这与 webpack 的 Node.js 环境不同。如果你需要此功能,请使用 webpack。未来 Turbopack 独立使用很可能需要 loader 配置。
Less计划通过插件支持目前默认不支持。一旦自定义 loader 稳定,很可能需要 loader 配置。
Lightning CSS使用中处理 CSS 转换。一些使用率较低的 CSS Modules 特性(如作为独立伪类的 :local/:global)尚不支持。请参阅下面的更多细节。

资源#

特性状态说明
静态资源(图片、字体)支持import img from './img.png' 开箱即用。在 Next.js 中,返回一个对象供 <Image /> 组件使用。
JSON 导入支持支持从 .json 进行命名导入或默认导入。

模块解析#

特性状态说明
路径别名支持读取 tsconfig.json 的 paths 和 baseUrl,与 Next.js 行为一致。
手动别名支持在 next.config.js 中配置 resolveAlias(类似于 webpack.resolve.alias)。
自定义扩展名支持在 next.config.js 中配置 resolveExtensions。
AMD部分支持基本转换可用;高级 AMD 用法受限。

性能与 Fast Refresh#

特性状态说明
Fast Refresh支持无需完全刷新即可更新 JavaScript、TypeScript 和 CSS。
增量打包支持Turbopack 惰性构建只构建开发服务器请求的内容,加快大型应用的速度。
文件系统缓存支持在多次运行之间将编译器产物持久化到磁盘。请参阅 turbopackFileSystemCache。

Magic Comments#

Turbopack 支持与 webpack 兼容的 magic comments,用于控制导入行为。这些注释适用于动态 import()、require()、require.resolve()、new Worker() 和 new URL() 表达式(不适用于静态 import 语句)。

注释WebpackTurbopack说明
webpackIgnore: true✓✓跳过打包,保留 import
turbopackIgnore: true✗✓跳过打包(仅限 Turbopack)
turbopackOptional: true✗✓抑制解析错误
webpackOptional: true✗✗不支持

有关用法示例,请参阅惰性加载。

import.meta.env#

Turbopack 通过 import.meta.env 支持内置的环境元数据:

属性类型值
DEVbooleanMODE 是否不是 "production"
PRODbooleanMODE 是否为 "production"
MODEstring编译时的 NODE_ENV,默认为 "development"
BASE_URLstringNext.js 的 basePath,带尾部斜杠(默认为 "/")
SSRboolean在服务端打包中为 true,在浏览器和客户端打包中为 false

这些值会被静态分析,因此 Turbopack 可以移除不可达的分支:

app/example.ts
if (import.meta.env.DEV) {
  console.log('development mode')
}

你也可以读取整个对象、对其进行解构,或使用静态方括号访问:

app/example.ts
const { MODE, SSR } = import.meta.env
const baseUrl = import.meta.env['BASE_URL']

小知识:import.meta.env 需要 Turbopack。不支持自定义的 VITE_* 变量、Vite 自定义模式、envPrefix 和 envDir。BASE_URL 反映 Next.js 的 basePath 配置,并包含尾部斜杠以匹配 Vite 的格式。

import.meta.glob#

Turbopack 支持 import.meta.glob(),这是一个与 Vite 兼容的 API,用于使用 glob 模式一次导入多个模块。结果是一个对象,其键是相对于调用文件的文件路径。

js
const modules = import.meta.glob('./dir/*.js')
// {
//   './dir/foo.js': () => import('./dir/foo.js'),
//   './dir/bar.js': () => import('./dir/bar.js'),
// }

小知识: import.meta.glob 需要 Turbopack。使用 webpack 时不可用。

模式#

模式可以是相对于导入文件的(./、../),也可以是相对于项目根目录的绝对路径(/):

js
// 相对于导入文件
const siblings = import.meta.glob('./dir/*.js')
const parent = import.meta.glob('../docs/*.js')

// 相对于项目根目录的绝对路径
const content = import.meta.glob('/content/*.md')

结果的键遵循以下模式:相对模式产生相对键('./dir/foo.js'、'../docs/intro.js'),项目根绝对路径模式产生项目根绝对键('/content/alpha.md')。

node_modules 与其他目录一样会被匹配,因此像 import.meta.glob('/**/*.js') 这样宽泛的模式也会遍历你的依赖项,可能需要几秒钟。请缩小模式范围,或使用否定模式排除不需要的内容。构建输出目录(.next)永远不会被遍历。

键始终按确定性的方式排序,且在开发和生产环境中完全一致。排序是对键进行逐字节比较,因此它不是自然顺序或显示顺序 —— '10-ten.js' 排在 '2-two.js' 之前,大写字母排在 _ 之前,_ 又排在小写字母之前,并且子目录中的文件与其同级文件交错排列,而不是分组。多个模式会合并成一个排序好的对象,而不是按模式顺序拼接。

惰性加载(默认)#

默认情况下,结果对象中的每个值都是一个 thunk —— 一个返回该模块 Promise 的函数。这实现了惰性加载:

js
const modules = import.meta.glob('./dir/*.js')

for (const path in modules) {
  const module = await modules[path]()
  console.log(path, module)
}

立即加载#

传入 { eager: true } 可一次性导入所有匹配的模块。每个值直接是模块对象,而不是 thunk:

js
const modules = import.meta.glob('./dir/*.js', { eager: true })

for (const path in modules) {
  console.log(path, modules[path].default)
}

命名导入#

使用 import 选项从每个匹配的模块中选择特定的命名导出。这在惰性和立即模式下都有效:

js
// 惰性:每个值是 () => Promise<exportValue>
const defaults = import.meta.glob('./dir/*.js', { import: 'default' })

// 立即:每个值直接是导出值
const setups = import.meta.glob('./dir/*.js', { import: 'setup', eager: true })

Query 字符串#

使用 query 选项为每个导入请求追加查询字符串:

js
const rawFiles = import.meta.glob('./dir/*.txt', { query: '?raw' })

query 选项也接受对象。键和值会进行 URL 编码并连接成一个查询字符串:

js
const modules = import.meta.glob('./*.ts', {
  query: { bar: 'foo', raw: true },
})
// 等同于:{ query: '?bar=foo&raw=true' }

query 会被传递给模块规则,它本身没有意义。与 Vite 不同,Turbopack 没有内置的 ?raw 或 ?url 处理,因此需要用规则匹配该 query,以决定这些文件如何加载:

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    rules: {
      // `import.meta.glob('./dir/*.txt', { query: '?raw' })` 以字符串形式返回文件内容
      '*.txt': { condition: { query: '?raw' }, type: 'text' },
    },
  },
}

export default nextConfig

多个模式与否定#

将 glob 模式数组作为第一个参数传入。在模式前加上 ! 可排除匹配的文件:

js
// 合并多个目录
const modules = import.meta.glob(['./dir/*.js', './other/*.js'])

// 排除特定文件
const withoutTests = import.meta.glob(['./src/**/*.js', '!**/*.test.js'])

基础路径#

使用 base 选项可将模式解析到不同的目录。结果的键随后相对于 base 而不是导入文件:

js
const modules = import.meta.glob('**/*.md', { base: '../../content' })
// {
//   './alpha.md': () => import('../../content/alpha.md'),
//   './nested/deep.md': () => import('../../content/nested/deep.md'),
// }

TypeScript#

import.meta.glob 的 TypeScript 类型已包含在 Next.js 中。当 tsconfig.json 中设置了 "moduleResolution": "bundler"(或 "node16" / "nodenext")时,它们会自动可用,这是新 Next.js 项目的默认设置。

返回类型根据 eager 选项而不同:

ts
// 惰性(默认)— Record<string, () => Promise<unknown>>
const lazy = import.meta.glob('./dir/*.ts')

// 立即 — Record<string, unknown>
const eager = import.meta.glob('./dir/*.ts', { eager: true })

传入模块类型以描述匹配文件导出的内容:

ts
interface Mod {
  name: string
  default: () => string
}

// Record<string, () => Promise<Mod>>
const lazy = import.meta.glob<Mod>('./dir/*.ts')

// Record<string, Mod>
const eager = import.meta.glob<Mod>('./dir/*.ts', { eager: true })

选项参考#

选项类型默认值说明
eagerbooleanfalse同步导入模块,而不是返回 thunk。
importstringundefined从每个匹配的模块中选择的命名导出(例如 'default')。
query`string \Record<string, string \boolean>`
basestringundefined解析模式所依据的目录,相对于导入文件。结果的键变为相对于它。
caseSensitivebooleantrue以区分大小写的方式匹配 glob 模式。设为 false 可忽略 ASCII 大小写。

注意: 不支持 as 选项(在 Vite 5 中已弃用)。请改用 query 搭配相应规则,如Query 字符串所示。旧版 import.meta.globEager() API 也不受支持 —— 请改用 import.meta.glob('...', { eager: true })。

与 webpack 的已知差异#

webpack 和 Turbopack 之间存在一些重要且非平凡的行为差异,在迁移应用时需要注意。通常,对于新应用来说,这些差异不太值得担心。

文件系统根目录#

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

例如,项目根目录之外的链接依赖(通过 npm link、yarn link、pnpm link 等)默认不会被解析。对于符号链接的依赖,请配置 experimental.turbopackAdditionalRoots。

当你的应用直接导入所检测根目录之外的文件(而不是通过符号链接访问它们)时,请使用 turbopack.root。

CSS Module 顺序#

Turbopack 会遵循 JS 导入顺序来为没有另行排序的 CSS modules 排序。例如:

components/BlogPost.jsx
import utilStyles from './utils.module.css'
import buttonStyles from './button.module.css'
export default function BlogPost() {
  return (
    <div className={utilStyles.container}>
      <button className={buttonStyles.primary}>Click me</button>
    </div>
  )
}

在此示例中,Turbopack 将确保 utils.module.css 在生成的 CSS chunk 中出现在 button.module.css 之前,遵循导入顺序。

Webpack 通常也会这样做,但有些情况下它会忽略 JS 推断的顺序,例如它推断 JS 文件是无副作用的。

如果应用依赖任意顺序,采用 Turbopack 时可能会导致细微的渲染变化。通常解决方法很简单,例如让 button.module.css @import utils.module.css 来强制指定顺序,或找出冲突的规则并更改它们,使其不针对相同的属性。

Sass node_modules 导入#

Turbopack 开箱即用地支持导入 node_modules 中的 Sass 文件。Webpack 支持一种旧版的波浪号 ~ 语法来实现这一点,Turbopack 不支持该语法。

从:

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

到:

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

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

next.config.js
module.exports = {
  turbopack: {
    resolveAlias: {
      '~*': '*',
    },
  },
}

CSS / Sass / SCSS 小数精度#

Turbopack 使用 Lightning CSS 编译 CSS。Lightning CSS 对数值型 CSS 值使用 5 位小数精度,而 webpack 使用 10 位。这同时适用于普通 CSS 和 Sass/SCSS 输出。例如,一个计算结果为 25/17 的值会产生:

  • Webpack: line-height: 1.4705882353(10 位)
  • Turbopack: line-height: 1.47059(5 位)

从 webpack 迁移到 Turbopack 时,这可能会导致细微的渲染差异,尤其是对于 line-height、letter-spacing 或其他高精度很重要的计算值等属性。

Webpack 插件#

Turbopack 不支持 webpack 插件。这会影响依赖 webpack 插件系统进行集成的第三方工具。我们确实支持 webpack loaders。如果你依赖 webpack 插件,则需要找到与 Turbopack 兼容的替代方案,或在等效功能可用之前继续使用 webpack。

不支持和不计划支持的功能#

有些功能尚未实现或不计划实现:

  • 旧版 CSS Modules 特性
    • 独立的 :local 和 :global 伪类(仅支持函数形式 :global(...))。
    • @value 规则(已被 CSS 变量取代)。
    • :import 和 :export ICSS 规则。
    • .module.css 中组合 .css 文件的 composes。在 webpack 中,这会将 .css 文件当作 CSS Module,而在 Turbopack 中,.css 文件始终是全局的。这意味着,如果你想在 CSS Module 中使用 composes,需要将 .css 文件改为 .module.css 文件。
    • CSS Modules 中将 .css 作为 CSS Module 导入的 @import。在 webpack 中,这会将 .css 文件当作 CSS Module,而在 Turbopack 中,.css 文件始终是全局的。这意味着,如果你想在 CSS Module 中使用 @import,需要将 .css 文件改为 .module.css 文件。
  • sassOptions.functions 不支持在 sassOptions.functions 中定义的自定义 Sass 函数。此特性允许定义可在编译期间从 Sass 代码调用的 JavaScript 函数。与完全用 JavaScript 运行的webpack 基于 Node.js 的 sass-loader 不同,Turbopack 基于 Rust 的架构无法直接执行通过 sassOptions.functions 传入的 JavaScript 函数。如果你使用自定义 Sass 函数,则需要使用 webpack 而不是 Turbopack。
  • next.config.js 中的 webpack() 配置 Turbopack 取代了 webpack,因此无法识别 webpack() 配置。请改用 turbopack 配置。
  • Yarn PnP 不计划在 Next.js 中为 Turbopack 提供支持。
  • experimental.urlImports 不计划为 Turbopack 提供支持。
  • experimental.esmExternals 不计划支持。Turbopack 不支持 Next.js 中旧版的 esmExternals 配置。
  • 一些 Next.js 实验性标志
    • experimental.nextScriptWorkers
    • experimental.fallbackNodePolyfills 我们计划在未来实现这些。

有关每个特性标志及其状态的完整详细细分,请参阅 Turbopack API 参考。

配置#

Turbopack 可以通过 next.config.js(或 next.config.ts)中的 turbopack 键进行配置。配置选项包括:

  • rules 为文件转换定义额外的 webpack loaders。
  • resolveAlias 创建手动别名(类似于 webpack 中的 resolve.alias)。
  • resolveExtensions 更改或扩展用于模块解析的文件扩展名。
  • ignoreIssue 从 CLI 输出和错误覆盖层中抑制特定的 Turbopack 错误和警告。

此外,next.config.js 中的 experimental 下提供以下实验性选项:

选项说明默认(dev)默认(build)
turbopackFileSystemCacheForDev为开发服务器启用文件系统缓存。true不适用
turbopackFileSystemCacheForBuild为构建启用文件系统缓存。不适用true<sup>1</sup>
turbopackGc从内存和持久缓存中移除不可达的工作。truetrue
turbopackLazyDynamicImports当浏览器首次请求客户端动态导入目标时对其进行编译。false不适用
turbopackLazyDynamicImportsSSR当服务端渲染首次到达动态导入目标时对其进行编译。false不适用
turbopackPluginRuntimeStrategy选择 Node.js 求值是在子进程还是 worker 线程中运行。'childProcesses''childProcesses'
turbopackMinify启用压缩。接受布尔值,或 { server, client, edge } 以分别配置每个环境。falsetrue
turbopackSourceMaps启用 source maps。trueproductionBrowserSourceMaps
turbopackInputSourceMaps启用从输入文件中提取 source maps。truetrue
turbopackModuleFragments目前处于活跃开发中。它将模块拆分为片段,chunk 只导入所用到的模块片段。falsefalse
turbopackRemoveUnusedImports启用移除未使用的导入。需要 turbopackRemoveUnusedExports。falsetrue
turbopackRemoveUnusedExports启用移除未使用的导出。falsetrue
turbopackMangleExportNames缩短模块彼此暴露的导出名称,以减小打包体积。导出名称可被观察到的模块(逃逸的命名空间对象、动态 import()、CommonJS require())会保留其原始名称。falsetrue
turbopackMangleViaMaterializedNamespaceObject允许通过具体化的命名空间门面进行导出名称混淆。当 turbopackMangleExportNames 显式为 true 时,默认为 true。falsefalse
turbopackInferModuleSideEffects启用本地分析以推断无副作用的模块,从而更好地进行 tree shaking。truetrue
turbopackScopeHoisting启用作用域提升。在 dev 模式下始终禁用。falsetrue
turbopackSharedRuntime在单个 runtime.js 资源中跨路由共享浏览器运行时。仅适用于生产构建。不适用true
turbopackClientSideNestedAsyncChunking为客户端资源启用嵌套异步分块。falsetrue
turbopackServerSideNestedAsyncChunking为服务端资源启用嵌套异步分块。falsefalse
turbopackImportTypeBytes为 ESM 导入启用对 with {type: "bytes"} 的支持。falsefalse
turbopackUseBuiltinBabel当存在 Babel 配置文件时,启用自动 Babel loader 配置。truetrue
turbopackUseBuiltinSass启用自动 Sass loader 配置。truetrue
turbopackModuleIds模块 ID 策略:'named' 或 'deterministic'。'named''deterministic'
turbopackLocalPostcssConfig先从 CSS 文件所在目录解析 postcss.config.js,然后才是项目根目录。falsefalse
turbopackWorkerAssetPrefix用于 Web Worker URL(入口点 + 模块 chunk)的自定义资源前缀,会覆盖 assetPrefix。与 webpack 的 output.workerPublicPath 类似。undefinedundefined

表格注释:

  1. 默认启用。当构建环境不会在多次构建之间保留 .next/cache 目录时,请将该选项设为 false。

例如,要在 turbopack 键下配置别名和自定义文件扩展名:

next.config.js
module.exports = {
  turbopack: {
    resolveAlias: {
      underscore: 'lodash',
    },
    resolveExtensions: [
      '.mdx',
      '.tsx',
      '.ts',
      '.jsx',
      '.js',
      '.mjs',
      '.node',
      '.json',
    ],
  },
}

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

生成用于性能调试的 trace 文件#

如果你遇到性能或内存问题,并希望帮助 Next.js 团队诊断它们,可以通过在 dev 命令中添加 --internal-trace 标志来生成 trace 文件:

bash
next dev --internal-trace

这将生成一个 .next-profiles/trace-turbopack.bin 文件。在 Next.js 仓库创建 GitHub issue 时请附上该文件,以帮助我们调查。

总结#

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

版本变更#

版本变更
v16.4.0借助 base 选项,import.meta.glob 的键相对于 base('./alpha.md'),而不是导入文件('../../content/alpha.md')。
v16.0.0对 build 的 Turbopack 支持已稳定,Turbopack 成为 Next.js 的默认打包器。当找到配置文件时自动支持 Babel。
v15.5.0对 build 的 Turbopack 支持进入 beta
v15.3.0对 build 的实验性支持
v15.0.0用于 dev 的 Turbopack 已稳定
Next.js 中文网