Sponsor
ntab.devntab.dev 提升效率的新标签页组件
点击查看
Menu

Next.js 编译器

Next.js 编译器使用 Rust 基于 SWC 构建,允许 Next.js 转换和压缩你的 JavaScript 代码以用于生产环境。这取代了用于单个文件的 Babel 和用于压缩输出包的 Terser。

使用 Next.js 编译器进行编译比 Babel 快 17 倍,并且自 Next.js 12 版本起默认启用。如果你有现有的 Babel 配置或正在使用不支持的功能,你的应用程序将选择退出 Next.js 编译器并继续使用 Babel。

为什么选择 SWC?

SWC 是一个可扩展的基于 Rust 的平台,用于下一代快速开发者工具。

SWC 可用于编译、压缩、打包等多种用途,并且设计为可扩展的。它是你可以调用来执行代码转换(内置或自定义)的工具。这些转换的运行通过像 Next.js 这样的高级工具进行。

我们选择基于 SWC 构建的原因有几个:

  • 可扩展性: SWC 可以作为 Next.js 内部的 Crate 使用,而无需分叉库或绕过设计约束。
  • 性能: 通过切换到 SWC,我们能够在 Next.js 中实现约 3 倍快的 Fast Refresh 和约 5 倍快的构建,还有更多优化空间正在进行中。
  • WebAssembly: Rust 对 WASM 的支持对于支持所有可能的平台和将 Next.js 开发带到各处至关重要。
  • 社区: Rust 社区和生态系统非常棒,而且仍在不断发展。

支持的功能

Styled Components

我们正在努力将 babel-plugin-styled-components 移植到 Next.js 编译器。

首先,更新到最新版本的 Next.js:npm install next@latest。然后,更新你的 next.config.js 文件:

next.config.js
module.exports = {
  compiler: {
    styledComponents: true,
  },
}

对于高级用例,你可以配置 styled-components 编译的各个属性。

注意:ssrdisplayName 转换是在 Next.js 中使用 styled-components 的主要要求。

next.config.js
module.exports = {
  compiler: {
    // 关于选项的更多信息,请参见 https://styled-components.com/docs/tooling#babel-plugin
    styledComponents: {
      // 在开发环境中默认启用,在生产环境中禁用以减小文件大小,
      // 设置此项将覆盖所有环境的默认值。
      displayName?: boolean,
      // 默认启用。
      ssr?: boolean,
      // 默认启用。
      fileName?: boolean,
      // 默认为空。
      topLevelImportPaths?: string[],
      // 默认为 ["index"]。
      meaninglessFileNames?: string[],
      // 默认启用。
      minify?: boolean,
      // 默认启用。
      transpileTemplateLiterals?: boolean,
      // 默认为空。
      namespace?: string,
      // 默认禁用。
      pure?: boolean,
      // 默认启用。
      cssProp?: boolean,
    },
  },
}

Jest

Next.js 编译器转译你的测试并简化了 Jest 与 Next.js 的配置,包括:

  • 自动模拟 .css.module.css(及其 .scss 变体)和图像导入
  • 使用 SWC 自动设置 transform
  • .env(及所有变体)加载到 process.env
  • 从测试解析和转换中忽略 node_modules
  • 从测试解析中忽略 .next
  • 加载 next.config.js 以获取启用实验性 SWC 转换的标志

首先,更新到最新版本的 Next.js:npm install next@latest。然后,更新你的 jest.config.js 文件:

jest.config.js
const nextJest = require('next/jest')
 
// 提供 Next.js 应用的路径,这将启用加载 next.config.js 和 .env 文件
const createJestConfig = nextJest({ dir: './' })
 
// 你想传递给 Jest 的任何自定义配置
const customJestConfig = {
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
}
 
// createJestConfig 以这种方式导出,以确保 next/jest 可以加载 Next.js 配置,这是异步的
module.exports = createJestConfig(customJestConfig)

Relay

要启用 Relay 支持:

next.config.js
module.exports = {
  compiler: {
    relay: {
      // 这应该与 relay.config.js 匹配
      src: './',
      artifactDirectory: './__generated__',
      language: 'typescript',
      eagerEsModules: false,
    },
  },
}

值得注意的是:在 Next.js 中,pages 目录中的所有 JavaScript 文件都被视为路由。因此,对于 relay-compiler,你需要指定 artifactDirectory 配置设置在 pages 目录之外,否则 relay-compiler 将在源文件旁边的 __generated__ 目录中生成文件,而这个文件将被视为路由,这将破坏生产构建。

移除 React 属性

允许移除 JSX 属性。这通常用于测试。类似于 babel-plugin-react-remove-properties

要移除匹配默认正则表达式 ^data-test 的属性:

next.config.js
module.exports = {
  compiler: {
    reactRemoveProperties: true,
  },
}

要移除自定义属性:

next.config.js
module.exports = {
  compiler: {
    // 这里定义的正则表达式在 Rust 中处理,所以语法与 JavaScript 的 `RegExp` 不同。
    // 参见 https://docs.rs/regex。
    reactRemoveProperties: { properties: ['^data-custom$'] },
  },
}

removeConsole

这个转换允许移除应用程序代码(非 node_modules)中的所有 console.* 调用。类似于 babel-plugin-transform-remove-console

移除所有 console.* 调用:

next.config.js
module.exports = {
  compiler: {
    removeConsole: true,
  },
}

移除 console.* 输出,但保留 console.error

next.config.js
module.exports = {
  compiler: {
    removeConsole: {
      exclude: ['error'],
    },
  },
}

传统装饰器

Next.js 将自动检测 jsconfig.jsontsconfig.json 中的 experimentalDecorators。传统装饰器通常与较旧版本的库(如 mobx)一起使用。

此标志仅为与现有应用程序的兼容性而支持。我们不建议在新应用程序中使用传统装饰器。

首先,更新到最新版本的 Next.js:npm install next@latest。然后,更新你的 jsconfig.jsontsconfig.json 文件:

{
  "compilerOptions": {
    "experimentalDecorators": true
  }
}

importSource

Next.js 将自动检测 jsconfig.jsontsconfig.json 中的 jsxImportSource 并应用它。这通常与 Theme UI 等库一起使用。

首先,更新到最新版本的 Next.js:npm install next@latest。然后,更新你的 jsconfig.jsontsconfig.json 文件:

{
  "compilerOptions": {
    "jsxImportSource": "theme-ui"
  }
}

Emotion

我们正在努力将 @emotion/babel-plugin 移植到 Next.js 编译器。

首先,更新到最新版本的 Next.js:npm install next@latest。然后,更新你的 next.config.js 文件:

next.config.js
 
module.exports = {
  compiler: {
    emotion: boolean | {
      // 默认为 true。当构建类型为生产环境时,它将被禁用。
      sourceMap?: boolean,
      // 默认为 'dev-only'。
      autoLabel?: 'never' | 'dev-only' | 'always',
      // 默认为 '[local]'。
      // 允许的值:`[local]` `[filename]` 和 `[dirname]`
      // 此选项仅在 autoLabel 设置为 'dev-only' 或 'always' 时有效。
      // 它允许你定义生成的标签的格式。
      // 格式通过字符串定义,其中变量部分用方括号 [] 括起来。
      // 例如 labelFormat: "my-classname--[local]",其中 [local] 将被替换为结果分配到的变量的名称。
      labelFormat?: string,
      // 默认为 undefined。
      // 此选项允许你告诉编译器它应该查看哪些导入来确定它应该转换什么,
      // 所以如果你重新导出 Emotion 的导出,你仍然可以使用转换。
      importMap?: {
        [packageName: string]: {
          [exportName: string]: {
            canonicalImport?: [string, string],
            styledBaseImport?: [string, string],
          }
        }
      },
    },
  },
}

压缩

自 v13 起,Next.js 的 swc 编译器默认用于压缩。这比 Terser 快 7 倍。

值得注意的是:从 v15 开始,不能再使用 next.config.js 自定义压缩。已移除对 swcMinify 标志的支持。

模块转译

Next.js 可以自动转译和打包来自本地包(如 monorepos)或外部依赖(node_modules)的依赖项。这替代了 next-transpile-modules 包。

next.config.js
module.exports = {
  transpilePackages: ['@acme/ui', 'lodash-es'],
}

模块化导入

此选项已在 Next.js 13.5 中被 optimizePackageImports 取代。我们建议升级以使用新选项,该选项不需要手动配置导入路径。

Define(在构建期间替换变量)

define 选项允许你在构建时静态替换代码中的变量。该选项接受一个对象作为键值对,其中键是应该被相应值替换的变量。

next.config.js 中使用 compiler.define 字段:

next.config.js
module.exports = {
  compiler: {
    define: {
      MY_STRING_VARIABLE: JSON.stringify('my-string'),
      MY_NUMBER_VARIABLE: '42',
    },
  },
}

实验性功能

SWC Trace 分析

你可以生成 SWC 的内部转换跟踪,格式为 chromium 的 trace event format

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

一旦启用,swc 将在 .next/ 下生成名为 swc-trace-profile-${timestamp}.json 的跟踪文件。Chromium 的跟踪查看器(chrome://tracing/、https://ui.perfetto.dev/)或兼容的火焰图查看器(https://www.speedscope.app/)可以加载和可视化生成的跟踪。

SWC 插件(实验性)

你可以配置 swc 的转换以使用 SWC 的实验性插件支持,这些插件用 wasm 编写,用于自定义转换行为。

next.config.js
module.exports = {
  experimental: {
    swcPlugins: [
      [
        'plugin',
        {
          ...pluginOptions,
        },
      ],
    ],
  },
}

swcPlugins 接受一个元组数组用于配置插件。插件的元组包含插件的路径和一个用于插件配置的对象。插件的路径可以是 npm 模块包名称或 .wasm 二进制文件本身的绝对路径。

不支持的功能

当你的应用程序有一个 .babelrc 文件时,Next.js 将自动回退到使用 Babel 来转换单个文件。这确保了与使用自定义 Babel 插件的现有应用程序的向后兼容性。

如果你正在使用自定义 Babel 设置,请分享你的配置。我们正在努力移植尽可能多的常用 Babel 转换,并在未来支持插件。

版本历史

版本变更
v13.1.0模块转译模块化导入 稳定版。
v13.0.0SWC 压缩器默认启用。
v12.3.0SWC 压缩器稳定版
v12.2.0添加了对 SWC 插件 的实验性支持。
v12.1.0添加了对 Styled Components、Jest、Relay、Remove React Properties、Legacy Decorators、Remove Console 和 jsxImportSource 的支持。
v12.0.0Next.js 编译器引入