NNext.js 中文网 GitHub

turbopack

使用 Turbopack 专属选项配置 Next.js。

turbopack 选项允许你自定义 Turbopack,以转换不同的文件并更改模块的解析方式。

小知识:在 Next.js 13.0.0 至 15.2.x 版本中,turbopack 选项曾命名为 experimental.turbo,该选项仍可作为别名使用,但新配置应使用顶层的 turbopack 选项。

如果你使用的是较旧版本的 Next.js,请运行 npx @next/codemod@latest next-experimental-turbo-to-turbopack . 自动迁移你的配置。

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

const nextConfig: NextConfig = {
  turbopack: {
    // ...
  },
}

export default nextConfig
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  turbopack: {
    // ...
  },
}

module.exports = nextConfig

小知识:

  • 用于 Next.js 的 Turbopack 的内置功能不需要 loader 或 loader 配置。Turbopack 内置支持 CSS 和编译现代 JavaScript,因此如果你使用 @babel/preset-env,就不需要 css-loader、postcss-loader 或 babel-loader。

参考#

选项#

turbopack 配置提供以下选项:

选项描述
root设置应用根目录。应为绝对路径。
rules使用 Turbopack 运行时要应用的受支持 webpack loader 列表。
resolveAlias将带别名的导入映射到要替代加载的模块。
resolveExtensions导入文件时要解析的扩展名列表。
debugIds在 JavaScript 包和 source map 中生成 debug ID。

支持的 loader#

以下 loader 已经过测试,可与 Turbopack 的 webpack loader 实现配合使用,但许多其他 webpack loader 即使未在此列出也应该可以工作:

缺失的 Webpack loader 功能#

Turbopack 使用 loader-runner 库来执行 webpack loader,该库提供了大部分标准 loader API。但是,某些功能不受支持:

模块加载:

文件系统和输出:

  • fs - 部分支持:已实现异步 fs.readFile 和 fs.stat。其他方法(包括同步文件系统方法)不受支持。
  • emitFile - 不支持

工具:

如果你有一个严重依赖这些功能之一的 loader,请提交 issue。

示例#

根目录#

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

不解析项目根目录之外的文件是为了改进缓存验证、减少文件系统监视开销,并减少所需的解析步骤数量。

Next.js 会自动检测项目的根目录。它通过查找以下文件之一来实现:

  • pnpm-lock.yaml
  • package-lock.json
  • yarn.lock
  • bun.lock
  • bun.lockb

如果你的项目结构不同,例如你不使用 workspaces,你可以手动设置 root 选项:

next.config.js
const path = require('path')
module.exports = {
  turbopack: {
    root: path.join(__dirname, '..'),
  },
}

要解析来自项目根目录之外的链接依赖中的文件(例如 [npm link]),你必须将 turbopack.root 配置为项目和链接依赖的共同父目录,或者配置一个额外的根目录。

在 monorepo 中工作时,可使用此选项配置根目录。不要将根目录设置得过于宽泛(例如设为你的主目录)。Turbopack 可能会监视根目录内的所有文件,配置过于宽泛的根目录可能导致严重的性能问题。

[npm link]: https://s.nodejs.cn/3cabbf7a-d071-4fc9-aca0-37dc3f1015ba

额外的根目录(实验性)#

experimental.turbopackAdditionalRoots 允许 Turbopack 跟随目标位于 turbopack.root 之外的符号链接。

这适用于位于项目外部的链接包(例如 npm link 或全局虚拟存储)。

额外的根目录只能在符号链接边界处跨越。不支持越过根目录的直接相对导入。

next.config.js
const path = require('path')

module.exports = {
  experimental: {
    turbopackAdditionalRoots: {
      linkedPackages: { path: path.join(__dirname, '../packages') },
    },
  },
}

每个 key 标识一个根目录。path 可以是绝对路径,也可以是相对于你运行 Next.js 的目录的路径。

小知识:

  • 在 next dev 或 next build 启动之前,符号链接及其目标都必须在构建机器上可用。
  • 部署工具和 CI 系统可能会将你的仓库复制到另一台构建机器。这些工具可能不知道额外的根目录,因而可能无法复制所需文件。
  • 在 Windows 上,构建需要开发者模式或提升的权限才能创建符号链接。创建输出产物可能需要创建符号链接。在某些情况下,当不允许创建符号链接时,Turbopack 可以回退到目录联接,但这些联接使用绝对路径,因此生成的输出可能无法重定位。

如果在 next build 或 next dev 启动时找不到某个根目录路径,则会发出警告,除非 ignoreIfMissing 设置为 true(默认为 false)。

为确保你的配置在各种平台(包括 Windows)上的可移植性,根目录名称必须满足以下所有要求:

  • 包含 1 到 40 个字符。
  • 每个字符必须是 ASCII 字母(a-z 或 A-Z)、数字(0-9)、下划线(_)或连字符(-)。
  • 不是 Windows 设备名称。
  • 在 ASCII 不区分大小写的比较下,不与之前的名称重复。

为避免对文件的引用产生歧义,额外的根目录不得与 turbopack.root 或彼此重叠。这意味着额外的根目录不能位于 turbopack.root 内部,也不能包含它。例如,同时将 foo/ 和 foo/bar/ 配置为额外的根目录会产生警告,且重叠的额外根目录将被忽略。

额外的根目录会改变 Next.js 的 trace 格式。

使用 output: "standalone" 时,存储在这些额外根目录中的未打包文件将被复制到输出目录中以该根目录命名的子目录。对于在 next.config.js 中配置的根目录,该目录名为配置的名称加上 @ 前缀(例如 next_additional_roots/@linkedPackages)。

全局虚拟存储#

某些包管理器可以将包安装到项目外部的全局虚拟存储中。将 experimental.turbopackDetectGlobalVirtualStore 设置为 true 可检测该存储,并将其添加为名为 gvs 的额外根目录。目前仅支持启用全局虚拟存储的 pnpm 11 或更高版本。

next.config.js
module.exports = {
  experimental: {
    turbopackDetectGlobalVirtualStore: true,
  },
}

Next.js 会读取 node_modules/.modules.yaml 中的 virtualStoreDir,从项目目录向上搜索到 turbopack.root。只有当该存储位于 turbopack.root 之外时,才会添加该根目录。

配置 webpack loader#

如果你需要超出内置功能的 loader 支持,许多 webpack loader 已经可以与 Turbopack 配合使用。目前存在一些限制:

  • 仅实现了 webpack loader API 的核心子集。目前,其覆盖范围足以支持一些流行的 loader,未来我们会扩展 API 支持。
  • 传给 webpack loader 的选项必须是普通的 JavaScript 原始值、对象和数组。例如,不能将 require() 插件模块作为选项值传入。

要配置 loader,请在 next.config.js 中添加你已安装的 loader 名称及任何选项,将文件扩展名映射到 loader 列表。规则按顺序求值。

下面是一个使用 @svgr/webpack loader 的示例,它支持导入 .svg 文件并将其渲染为 React 组件。

next.config.js
module.exports = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}

小知识:rules 对象中使用的 glob 基于文件名进行匹配,除非 glob 包含 / 字符,此时将基于完整的相对于项目的文件路径进行匹配。Windows 文件路径会被规范化为使用 unix 风格的 / 路径分隔符。

Turbopack 使用经过修改的 Rust globset 库。

as 会重命名 loader 的输出,使其根据新的扩展名进行处理。* 代表原始文件名,因此 as: '*.js' 会使 icon.svg 被视为 icon.svg.js。当 as 以一个前导 * 开头,后跟文件名已经具有的后缀时,名称保持不变。例如,对 '*.css' 规则使用 as: '*.css' 会使 styles.module.css 保持不变,因此它仍作为 CSS Module 处理。

对于需要配置选项的 loader,你可以使用对象格式代替字符串:

next.config.js
module.exports = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: [
          {
            loader: '@svgr/webpack',
            options: {
              icon: true,
            },
          },
        ],
        as: '*.js',
      },
    },
  },
}

小知识:在 Next.js 13.4.4 版本之前,turbopack.rules 名为 turbo.loaders,且只接受像 .mdx 这样的文件扩展名,而不是 *.mdx。

高级 webpack loader 条件#

你可以使用高级 condition 语法进一步限制 loader 的运行位置:

next.config.js
module.exports = {
  turbopack: {
    rules: {
      // '*' 将匹配所有文件路径,但我们使用条件限制
      // 规则的生效范围。
      '*': {
        condition: {
          all: [
            // 'foreign' 是一个内置条件。
            { not: 'foreign' },
            // 'path' 可以是 RegExp 或 glob 字符串。RegExp 匹配
            // 完整的项目相对文件路径中的任意位置。
            { path: /^img\/[0-9]{3}\// },
            {
              any: [
                { path: '*.svg' },
                // 'query' 匹配完整查询字符串中的任意位置,
                // 查询字符串可以为空,或以 `?` 开头。
                { query: /[?&]svgr(?=&|$)/ },
                // 'content' 始终是 RegExp,可以匹配
                // 文件中的任意位置。
                { content: /\<svg\W/ },
              ],
            },
          ],
        },
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}
  • 支持的布尔运算符有 {all: [...]}、{any: [...]} 和 {not: ...}。
  • 支持的可自定义运算符有 {path: string | RegExp}、{content: RegExp}、{query: string | RegExp} 和 {contentType: string | RegExp}。如果在同一对象中指定多个运算符,则相当于隐式的 and。
    • path 针对项目相对文件路径进行匹配。字符串被视为 glob 模式,而 RegExp 可用于部分匹配路径。
    • content 匹配文件内容中的任意位置。
    • query 匹配导入的查询字符串(例如 import './file?foo' 中的 ?foo)。字符串必须完全匹配,而 RegExp 可用于部分匹配查询字符串。
    • contentType 匹配资源的 MIME 内容类型(例如来自 data:text/plain,... 之类 data URL 的类型)。字符串被视为 glob 模式(例如 text/*、image/*),而 RegExp 可用于部分匹配内容类型。

此外,还支持若干内置条件:

  • browser:匹配将在客户端执行的代码。可使用 {not: 'browser'} 匹配服务端代码。
  • foreign:匹配 node_modules 中的代码以及一些 Next.js 内部代码。通常你会希望将 loader 限制为 {not: 'foreign'}。这可以通过减少 loader 被调用的文件数量来提升性能。
  • development:匹配使用 next dev 的情况。
  • production:匹配使用 next build 的情况。
  • node:匹配将在默认 Node.js 运行时上运行的代码。
  • edge-light:匹配将在 Edge runtime 上运行的代码(已弃用)。

规则可以是对象或对象数组。数组通常有助于表达互斥条件:

next.config.js
module.exports = {
  turbopack: {
    rules: {
      '*.svg': [
        {
          condition: 'browser',
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
        {
          condition: { not: 'browser' },
          loaders: [require.resolve('./custom-svg-loader.js')],
          as: '*.js',
        },
      ],
    },
  },
}

小知识:所有匹配的规则都会按顺序执行。

模块类型#

你可以直接设置模块类型,而无需使用 loader。这有助于更改文件的处理方式,类似于 webpack 的 type 选项。

next.config.js
module.exports = {
  turbopack: {
    rules: {
      '*.svg': {
        type: 'asset',
      },
    },
  },
}

使用 type: 'asset' 时,导入文件会返回其 URL:

app/page.tsx
import svgUrl from './icon.svg'

export default function Page() {
  return <img src={svgUrl} alt="Icon" />
}

type 选项可与 loaders 结合使用 - loader 先运行,然后结果按指定类型进行处理。

可用的模块类型:

类型描述
asset输出文件并返回 URL(类似 webpack 的 asset/resource)
ecmascript作为 JavaScript 处理
typescript作为 TypeScript 处理
css作为 CSS 处理
css-module作为 CSS Module 处理
json解析为 JSON 并导出
wasm作为 WebAssembly 处理
node作为原生 Node.js 插件处理
raw将内容作为字符串导出(text 的别名)
text将内容作为字符串导出
bytes将内容作为 Uint8Array 导出

通过 import attributes 内联配置 loader#

你可以使用 with 子句(import attributes)将 Turbopack loader 应用于单个导入。这是按导入进行指定,而非通过 turbopack.rules 全局指定。

当你希望对某个特定导入应用 loader,而不影响该类型的所有文件时,这很有用。

app/page.tsx
// 应用 raw loader,将 .txt 文件作为 JavaScript 模块导入
import rawText from '../data.txt' with { turbopackLoader: 'raw-loader', turbopackAs: '*.js' }

export default function Page() {
  return <p>{rawText}</p>
}

支持以下 import attributes:

属性描述
turbopackLoader要应用的 loader(例如 'raw-loader')。
turbopackLoaderOptionsloader 选项的 JSON 字符串(例如 '{"search":"X","replace":"Y"}')。
turbopackAs输出的重命名模式(与 turbopack.rules[].as 相同)。例如,'*.js' 将 loader 输出视为 JavaScript。
turbopackModuleType设置输出的模块类型(与 turbopack.rules[].type 相同)。

带选项的 loader 通过 turbopackLoaderOptions 传递 JSON 编码的字符串:

app/page.tsx
import value from '../data.js' with { turbopackLoader: 'string-replace-loader', turbopackLoaderOptions: '{"search":"PLACEHOLDER","replace":"replaced value"}' }

小知识:带有 turbopackLoader 的 import attributes 是 Turbopack 特有的,webpack 不支持。此功能要求你的导入语句使用 with 关键字(而非 assert)。

解析别名#

可以配置 Turbopack 通过别名修改模块解析,类似于 webpack 的 resolve.alias 配置。

要配置解析别名,请在 next.config.js 中将导入模式映射到新的目标:

next.config.js
module.exports = {
  turbopack: {
    resolveAlias: {
      underscore: 'lodash',
      mocha: { browser: 'mocha/browser-entry.js' },
    },
  },
}

这会将 underscore 包的导入别名化为 lodash 包。换句话说,import underscore from 'underscore' 将加载 lodash 模块,而不是 underscore。

Turbopack 还支持通过此字段进行条件别名化,类似于 Node.js 的 conditional exports。目前仅支持 browser 条件。在上面的例子中,当 Turbopack 面向浏览器环境时,对 mocha 模块的导入将被别名化为 mocha/browser-entry.js。

解析自定义扩展名#

可以配置 Turbopack 使用自定义扩展名解析模块,类似于 webpack 的 resolve.extensions 配置。

要配置解析扩展名,请使用 next.config.js 中的 resolveExtensions 字段:

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

这会以提供的列表覆盖默认的解析扩展名,因此请包含你仍需要的每个扩展名。默认值为 .tsx、.ts、.jsx、.js、.mjs 和 .json,服务端解析还会为原生模块添加 .node。在客户端列出 .node 是无害的,因此一个列表可以同时覆盖两者。

小知识:这适用于你自己的源文件。在 node_modules 内部解析的导入保留其自身的扩展名列表,不受此选项影响。

有关如何将应用从 webpack 迁移到 Turbopack 的更多信息和指南,请参阅 Turbopack 关于 webpack 兼容性的文档。

Debug ID#

可以配置 Turbopack 在 JavaScript 包和 source map 中生成 debug ID。

要配置 debug ID,请使用 next.config.js 中的 debugIds 字段:

next.config.js
module.exports = {
  turbopack: {
    debugIds: true,
  },
}

该选项会自动向 JavaScript 包添加 debug ID 的 polyfill 以确保兼容性。这些 debug ID 可通过全局变量 globalThis._debugIds 访问。

版本历史#

版本变更
16.5.0新增 experimental.turbopackDetectGlobalVirtualStore
16.4.0新增 experimental.turbopackAdditionalRoots
16.2.0新增 turbopackLoader import attributes。
16.2.0新增 turbopack.rules.*.type。
16.2.0新增 turbopack.rules.*.condition.contentType。
16.2.0新增 turbopack.rules.*.condition.query。
16.0.0新增 turbopack.debugIds。
16.0.0新增 turbopack.rules.*.condition。
15.3.0experimental.turbo 更改为 turbopack。
13.0.0引入 experimental.turbo。
Next.js 中文网