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 可以作为 Crate 在 Next.js 内部使用，无需分叉库或绕过设计限制。
性能： 通过切换到 SWC，我们能够在 Next.js 中实现约 3 倍的快速刷新和约 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 编译的各个属性。

注意：ssr 和 displayName 转换是使用 styled-components 在 Next.js 中的主要需求。

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 编译器会转译你的测试，并简化与 Next.js 一起配置 Jest，包括：

自动模拟 .css、.module.css（及其 .scss 变体）和图片导入
自动设置 transform 使用 SWC
将 .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$"] },
  },
};

移除控制台

此转换允许移除应用程序代码中的所有 console.* 调用（不包括 node_modules）。类似于 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.json 或 tsconfig.json 中的 experimentalDecorators。传统装饰器通常与 mobx 等库的旧版本一起使用。

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

首先，更新到最新版本的 Next.js：npm install next@latest。然后，更新你的 jsconfig.json 或 tsconfig.json 文件：

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

importSource

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

首先，更新到最新版本的 Next.js：npm install next@latest。然后，更新你的 jsconfig.json 或 tsconfig.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],
          }
        }
      },
    },
  },
}

压缩

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

如果出于任何原因仍需要 Terser，可以进行配置。

next.config.js

module.exports = {
  swcMinify: false,
};

模块转译

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

next.config.js

module.exports = {
  transpilePackages: ["@acme/ui", "lodash-es"],
};

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.0`	SWC 压缩器默认启用。
`v12.3.0`	SWC 压缩器稳定。
`v12.2.0`	添加对 SWC 插件的实验性支持。
`v12.1.0`	添加对 Styled Components、Jest、Relay、移除 React 属性、传统装饰器、移除控制台和 jsxImportSource 的支持。
`v12.0.0`	Next.js 编译器引入。

Next.js 编译器

为什么选择 SWC？

支持的功能

Styled Components

Jest

Relay

移除 React 属性

移除控制台

传统装饰器

importSource

Emotion

压缩

模块转译

模块化导入

实验性功能

SWC 跟踪分析

SWC 插件（实验性）

不支持的功能

版本历史