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 |
| Windows | x64、ARM64 |
| Linux (glibc) | x64、ARM64 |
| Linux (musl) | x64、ARM64 |
在没有原生绑定的平台(例如 FreeBSD、OpenBSD)上,Next.js 会回退到 WebAssembly (WASM) 绑定。WASM 绑定支持核心 SWC 特性,如编译和压缩,但不支持 Turbopack。在这些平台上,请使用 --webpack 标志:
next dev --webpack
next build --webpack快速开始#
Turbopack 现在是 Next.js 中的默认打包器。无需任何配置即可使用 Turbopack:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
}
}改用 Webpack#
如果你需要使用 Webpack 而不是 Turbopack,可以通过 --webpack 标志选择加入:
{
"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 语句)。
| 注释 | Webpack | Turbopack | 说明 |
|---|---|---|---|
webpackIgnore: true | ✓ | ✓ | 跳过打包,保留 import |
turbopackIgnore: true | ✗ | ✓ | 跳过打包(仅限 Turbopack) |
turbopackOptional: true | ✗ | ✓ | 抑制解析错误 |
webpackOptional: true | ✗ | ✗ | 不支持 |
有关用法示例,请参阅惰性加载。
import.meta.env#
Turbopack 通过 import.meta.env 支持内置的环境元数据:
| 属性 | 类型 | 值 |
|---|---|---|
DEV | boolean | MODE 是否不是 "production" |
PROD | boolean | MODE 是否为 "production" |
MODE | string | 编译时的 NODE_ENV,默认为 "development" |
BASE_URL | string | Next.js 的 basePath,带尾部斜杠(默认为 "/") |
SSR | boolean | 在服务端打包中为 true,在浏览器和客户端打包中为 false |
这些值会被静态分析,因此 Turbopack 可以移除不可达的分支:
if (import.meta.env.DEV) {
console.log('development mode')
}你也可以读取整个对象、对其进行解构,或使用静态方括号访问:
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 模式一次导入多个模块。结果是一个对象,其键是相对于调用文件的文件路径。
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 时不可用。
模式#
模式可以是相对于导入文件的(./、../),也可以是相对于项目根目录的绝对路径(/):
// 相对于导入文件
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 的函数。这实现了惰性加载:
const modules = import.meta.glob('./dir/*.js')
for (const path in modules) {
const module = await modules[path]()
console.log(path, module)
}立即加载#
传入 { eager: true } 可一次性导入所有匹配的模块。每个值直接是模块对象,而不是 thunk:
const modules = import.meta.glob('./dir/*.js', { eager: true })
for (const path in modules) {
console.log(path, modules[path].default)
}命名导入#
使用 import 选项从每个匹配的模块中选择特定的命名导出。这在惰性和立即模式下都有效:
// 惰性:每个值是 () => Promise<exportValue>
const defaults = import.meta.glob('./dir/*.js', { import: 'default' })
// 立即:每个值直接是导出值
const setups = import.meta.glob('./dir/*.js', { import: 'setup', eager: true })Query 字符串#
使用 query 选项为每个导入请求追加查询字符串:
const rawFiles = import.meta.glob('./dir/*.txt', { query: '?raw' })query 选项也接受对象。键和值会进行 URL 编码并连接成一个查询字符串:
const modules = import.meta.glob('./*.ts', {
query: { bar: 'foo', raw: true },
})
// 等同于:{ query: '?bar=foo&raw=true' }query 会被传递给模块规则,它本身没有意义。与 Vite 不同,Turbopack 没有内置的 ?raw 或 ?url 处理,因此需要用规则匹配该 query,以决定这些文件如何加载:
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 模式数组作为第一个参数传入。在模式前加上 ! 可排除匹配的文件:
// 合并多个目录
const modules = import.meta.glob(['./dir/*.js', './other/*.js'])
// 排除特定文件
const withoutTests = import.meta.glob(['./src/**/*.js', '!**/*.test.js'])基础路径#
使用 base 选项可将模式解析到不同的目录。结果的键随后相对于 base 而不是导入文件:
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 选项而不同:
// 惰性(默认)— Record<string, () => Promise<unknown>>
const lazy = import.meta.glob('./dir/*.ts')
// 立即 — Record<string, unknown>
const eager = import.meta.glob('./dir/*.ts', { eager: true })传入模块类型以描述匹配文件导出的内容:
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 })选项参考#
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
eager | boolean | false | 同步导入模块,而不是返回 thunk。 |
import | string | undefined | 从每个匹配的模块中选择的命名导出(例如 'default')。 |
query | `string \ | Record<string, string \ | boolean>` |
base | string | undefined | 解析模式所依据的目录,相对于导入文件。结果的键变为相对于它。 |
caseSensitive | boolean | true | 以区分大小写的方式匹配 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 排序。例如:
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 不支持该语法。
从:
@import '~bootstrap/dist/css/bootstrap.min.css';到:
@import 'bootstrap/dist/css/bootstrap.min.css';如果你无法更新导入,可以添加 turbopack.resolveAlias 配置,将 ~ 语法映射到实际路径:
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和:exportICSS 规则。.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.nextScriptWorkersexperimental.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 | 从内存和持久缓存中移除不可达的工作。 | true | true |
turbopackLazyDynamicImports | 当浏览器首次请求客户端动态导入目标时对其进行编译。 | false | 不适用 |
turbopackLazyDynamicImportsSSR | 当服务端渲染首次到达动态导入目标时对其进行编译。 | false | 不适用 |
turbopackPluginRuntimeStrategy | 选择 Node.js 求值是在子进程还是 worker 线程中运行。 | 'childProcesses' | 'childProcesses' |
turbopackMinify | 启用压缩。接受布尔值,或 { server, client, edge } 以分别配置每个环境。 | false | true |
turbopackSourceMaps | 启用 source maps。 | true | productionBrowserSourceMaps |
turbopackInputSourceMaps | 启用从输入文件中提取 source maps。 | true | true |
turbopackModuleFragments | 目前处于活跃开发中。它将模块拆分为片段,chunk 只导入所用到的模块片段。 | false | false |
turbopackRemoveUnusedImports | 启用移除未使用的导入。需要 turbopackRemoveUnusedExports。 | false | true |
turbopackRemoveUnusedExports | 启用移除未使用的导出。 | false | true |
turbopackMangleExportNames | 缩短模块彼此暴露的导出名称,以减小打包体积。导出名称可被观察到的模块(逃逸的命名空间对象、动态 import()、CommonJS require())会保留其原始名称。 | false | true |
turbopackMangleViaMaterializedNamespaceObject | 允许通过具体化的命名空间门面进行导出名称混淆。当 turbopackMangleExportNames 显式为 true 时,默认为 true。 | false | false |
turbopackInferModuleSideEffects | 启用本地分析以推断无副作用的模块,从而更好地进行 tree shaking。 | true | true |
turbopackScopeHoisting | 启用作用域提升。在 dev 模式下始终禁用。 | false | true |
turbopackSharedRuntime | 在单个 runtime.js 资源中跨路由共享浏览器运行时。仅适用于生产构建。 | 不适用 | true |
turbopackClientSideNestedAsyncChunking | 为客户端资源启用嵌套异步分块。 | false | true |
turbopackServerSideNestedAsyncChunking | 为服务端资源启用嵌套异步分块。 | false | false |
turbopackImportTypeBytes | 为 ESM 导入启用对 with {type: "bytes"} 的支持。 | false | false |
turbopackUseBuiltinBabel | 当存在 Babel 配置文件时,启用自动 Babel loader 配置。 | true | true |
turbopackUseBuiltinSass | 启用自动 Sass loader 配置。 | true | true |
turbopackModuleIds | 模块 ID 策略:'named' 或 'deterministic'。 | 'named' | 'deterministic' |
turbopackLocalPostcssConfig | 先从 CSS 文件所在目录解析 postcss.config.js,然后才是项目根目录。 | false | false |
turbopackWorkerAssetPrefix | 用于 Web Worker URL(入口点 + 模块 chunk)的自定义资源前缀,会覆盖 assetPrefix。与 webpack 的 output.workerPublicPath 类似。 | undefined | undefined |
表格注释:
- 默认启用。当构建环境不会在多次构建之间保留
.next/cache目录时,请将该选项设为false。
例如,要在 turbopack 键下配置别名和自定义文件扩展名:
module.exports = {
turbopack: {
resolveAlias: {
underscore: 'lodash',
},
resolveExtensions: [
'.mdx',
'.tsx',
'.ts',
'.jsx',
'.js',
'.mjs',
'.node',
'.json',
],
},
}有关更深入的配置示例,请参阅 Turbopack 配置文档。
生成用于性能调试的 trace 文件#
如果你遇到性能或内存问题,并希望帮助 Next.js 团队诊断它们,可以通过在 dev 命令中添加 --internal-trace 标志来生成 trace 文件:
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 已稳定 |