升级到 Babel 8

本文档列出了 Babel 8.0.0 中引入的重大更改，以及从 Babel 7.0.0 升级时如何调整 Babel 的使用以适应这些更改。

¥This document lists the breaking changes introduced in Babel 8.0.0, and how to adapt your usage of Babel to them when upgrading from Babel 7.0.0.

如果你直接使用 Babel 的 API（例如，因为你维护一个自定义的 Babel 插件），也请检查集成迁移指南。

¥If you are working directly with Babel's API (because, for example, you maintain a custom Babel plugin), please also check the migration guide for integration.

如果你要从 Babel 6 升级，请先检查 Babel 7 迁移指南。

¥If you are upgrading from Babel 6, please check the Babel 7 migration guide first.

准备工作

¥Getting ready

在迁移到 Babel 8 之前，我们建议你更新 Babel 7 配置，使其与 Babel 8 的新默认配置保持一致。当你的构建过程再次与 Babel 7 兼容后，你就可以升级到 Babel 8。

¥Before migrating to Babel 8, we recommend that you update your Babel 7 configuration to align it with Babel 8's new defaults. Once your build process is working again with Babel 7, you can then upgrade to Babel 8.

你应该阅读完整的文档，以了解需要更改哪些选项以及需要删除哪些插件，但以下是更新配置的最重要步骤：

¥You should read this full document to understand what options you need to change and which plugins you need to remove, but here are the most important steps to modernize your config:

如果你不使用 .browserslistrc 文件，请定义一个顶层 targets 选项。Babel 7 默认为 targets: ">= 0%"（所有浏览器），而 Babel 8 默认为 targets: "defaults"。如果你正在使用 @babel/preset-env 的 targets 选项，请将其值复制到顶层配置（presets 旁边）。

¥If you are not using a .browserslistrc file, define a top-level targets option. Babel 7 defaults to targets: ">= 0%" (all browsers), while Babel 8 defaults to targets: "defaults". If you are using @babel/preset-env's targets option, copy its value to the top-level configuration (next to presets).
如果你使用 @babel/preset-env，请启用其 bugfixes 选项。

¥If you use @babel/preset-env, enable its bugfixes option.
如果你使用 @babel/preset-env 的 loose 或 spec 选项，则迁移到 assumptions。

¥If you use @babel/preset-env's loose or spec options, migrate to assumptions.
如果你使用 @babel/preset-react 或 @babel/plugin-transform-react-jsx，请显式设置它们的 runtime 选项（Babel 7 默认为 "classic"，Babel 8 默认为 "automatic"）。如果你继续使用经典运行时，请将 useSpread 选项设置为 true。

¥If you use @babel/preset-react or @babel/plugin-transform-react-jsx, explicitly set their runtime option (Babel 7 defaults to "classic", Babel 8 to "automatic"). If you keep using the classic runtime, set the useSpread option to true.
如果你使用 TypeScript 或 Flow 预设，请将 isTSX 和 allExtensions 选项替换为 ignoreExtensions。

¥If you use the TypeScript or Flow presets, replace the isTSX and allExtensions options with ignoreExtensions.
如果你正在转换 TypeScript 或 Flow，请将 allowDeclareFields 选项设置为 true（参见 TypeScript）。

¥If you are transforming TypeScript or Flow, set the allowDeclareFields option to true (see TypeScript).
如果你使用 @babel/plugin-transform-runtime 的 corejs 或 @babel/preset-env 的 useBuiltIns 选项，请移除它们并改用 babel-plugin-polyfill-corejs3。

¥If you use @babel/plugin-transform-runtime's corejs or @babel/preset-env's useBuiltIns options, remove them and use babel-plugin-polyfill-corejs3 instead.
如果你使用 @babel/plugin-proposal-decorators，请将其 version 选项设置为 legacy 或 2023-11。

¥If you use @babel/plugin-proposal-decorators, set its version option to legacy or 2023-11.
如果你正在使用 @babel/plugin-proposal-record-and-tuple 和 @babel/plugin-syntax-import-assertions 插件，请将其移除。

¥Remove the @babel/plugin-proposal-record-and-tuple and @babel/plugin-syntax-import-assertions plugins if you are using them.

Babel

Node.js 支持

¥Node.js support

所有 Babel 8 软件包都需要 Node.js ^20.19.0 || >=22.12.0。

¥All Babel 8 packages require Node.js ^20.19.0 || >=22.12.0.

我们强烈建议你使用较新版本的 Node.js (LTS v22)，因为之前的版本已不再维护。有关详细信息，请参阅 nodejs/Release。

¥We highly encourage you to use a newer version of Node.js (LTS v22) since the previous versions are not maintained. See nodejs/Release for more information.

这只是意味着 Babel 本身不会在旧版本的 Node.js 上运行。它仍然可以输出在旧 Node 版本上运行的代码。

¥This just means Babel itself won't run on older versions of Node. It can still output code that runs on old Node versions.

仅限 ESM

¥ESM only

Babel 现在以原生 ECMAScript 模块（#11701、#17265）的形式提供。

¥Babel is now shipped as native ECMAScript modules (#11701, #17265).

对等依赖要求

¥Peer dependency requirements

所有预设和插件都需要 @babel/core@^8.0.0 作为对等依赖。一些 Babel 7 插件和预设可能与 @babel/core@8 兼容，一些 Babel 8 插件和预设可能与 @babel/core@7 兼容，但我们不提供任何官方支持。

¥All presets and plugins require @babel/core@^8.0.0 as peer dependency. Some Babel 7 plugins and presets might work with @babel/core@8, and some Babel 8 plugins and presets might work with @babel/core@7, but we do not provide any official support for that.
@babel/eslint-parser 和 @babel/eslint-plugin 都需要 eslint@^8.9.0 作为对等依赖。(#15563)

¥@babel/eslint-parser and @babel/eslint-plugin require eslint@^8.9.0 as peer dependency. (#15563)

重命名的软件包

¥Renamed Packages

以下软件包已从 ...-proposal-... 重命名为 ...-transform-...，因为它们已达到第 4 阶段（#15614）。Babel 7.22 中已引入重命名过程，因此你可以在升级之前开始迁移。

¥The following packages has been renamed from ...-proposal-... to ...-transform-..., as they have reached Stage 4 (#15614). The rename process has been landed in Babel 7.22 so you can start the migration prior to the upgrade.

Babel 7	Babel 8
`@babel/plugin-proposal-async-generator-functions`	`@babel/plugin-transform-async-generator-functions`
`@babel/plugin-proposal-class-properties`	`@babel/plugin-transform-class-properties`
`@babel/plugin-proposal-class-static-block`	`@babel/plugin-transform-class-static-block`
`@babel/plugin-proposal-duplicate-named-capturing-groups-regex`	`@babel/plugin-transform-duplicate-named-capturing-groups-regex`
`@babel/plugin-proposal-dynamic-import`	`@babel/plugin-transform-dynamic-import`
`@babel/plugin-proposal-explicit-resource-management`	`@babel/plugin-transform-explicit-resource-management`
`@babel/plugin-proposal-export-namespace-from`	`@babel/plugin-transform-export-namespace-from`
`@babel/plugin-proposal-json-strings`	`@babel/plugin-transform-json-strings`
`@babel/plugin-proposal-logical-assignment-operators`	`@babel/plugin-transform-logical-assignment-operators`
`@babel/plugin-proposal-nullish-coalescing-operator`	`@babel/plugin-transform-nullish-coalescing-operator`
`@babel/plugin-proposal-numeric-separator`	`@babel/plugin-transform-numeric-separator`
`@babel/plugin-proposal-object-rest-spread`	`@babel/plugin-transform-object-rest-spread`
`@babel/plugin-proposal-optional-catch-binding`	`@babel/plugin-transform-optional-catch-binding`
`@babel/plugin-proposal-optional-chaining`	`@babel/plugin-transform-optional-chaining`
`@babel/plugin-proposal-private-methods`	`@babel/plugin-transform-private-methods`
`@babel/plugin-proposal-private-property-in-object`	`@babel/plugin-transform-private-property-in-object`
`@babel/plugin-proposal-unicode-property-regex`	`@babel/plugin-transform-unicode-property-regex`

已停用的软件包

¥Discontinued Packages

`@babel/runtime-corejs2`

core-js@2 多年未维护，你应该改用 core-js@3。

¥core-js@2 has not been maintained for years, and you should switch to core-js@3 instead.

请升级到 @babel/runtime-corejs3（#11751）。安装新的运行时后，请将 corejs 版本设置为你正在使用的 core-js 版本。

¥Please upgrade to @babel/runtime-corejs3 (#11751). After you install the new runtime, please set the corejs version to the core-js version that you are using.

babel.config.json
  {
    "plugins": [
-     ["@babel/transform-runtime", { corejs: 2 }]
+     "@babel/transform-runtime",
+     ["babel-plugin-polyfill-corejs3", { method: "usage-pure", version: "3.42.0" }]
    ]
  }

`@babel/plugin-syntax-import-assertions`

该提案演变为导入属性，现在 Babel 默认支持解析。你可以从配置中删除 @babel/plugin-syntax-import-assertions，并在代码库中替换以下模式：

¥The proposal evolved into import attributes, which now Babel supports parsing by default. You can remove @babel/plugin-syntax-import-assertions from your config, and replace the following patterns in your codebase:

input.js
- import value from "module" assert { type: "json" };
+ import value from "module" with { type: "json" };

`@babel/plugin-proposal-record-and-tuple`

记录和元组提案已在 TC39 中撤回，这意味着该语法不再适合包含在语言中。

¥The Records and Tuples proposal has been withdrawn in TC39, which means that the syntax is not on track anymore to be included in the language.

你需要放弃 Records 和 Tuples 语法，并可以直接使用 @bloomberg/record-tuple-polyfill polyfill，就像它是一个独立的库一样。

¥You will need to migrate away from the Records and Tuples syntax, and you can directly use the @bloomberg/record-tuple-polyfill polyfill as if it was a standalone library.

input.mjs
+ import { Record, Tuple } from "@bloomberg/record-tuple-polyfill"

// syntaxType: "hash"

- #{ p: "value" }
+ Record({ p: "value" })

- #[0, 1, 2]
+ Tuple(0, 1, 2)

// syntaxType: "bar"
- {| p: "value" |}
+ Record({ p: "value" })

- [|0, 1, 2|]
+ Tuple(0, 1, 2)

如果你必须进行大规模迁移。你可以仅使用 @babel/plugin-proposal-record-and-tuple 插件运行 Babel 7 来转换代码库：

¥If you have to do a large scale migration. You can run Babel 7 with only the @babel/plugin-proposal-record-and-tuple plugin to transform the code base:

babel.record-tuple-migration.config.json
{
  "babelrc": false,
  "configFile": false,
  "generateOpts": {
    "experimental_preserveFormat": true,
    "retainLines": true,
    "tokens": true
  },
  "parserOpts": {
    "createParenthesizedExpressions": true
  },
  "plugins": [
    "@babel/plugin-syntax-jsx",
    "@babel/plugin-syntax-typescript",

    // or syntaxType: "bar" if you are using `{||}` or `[||]`
    ["@babel/plugin-proposal-record-and-tuple", {
      "syntaxType": "hash", "importPolyfill": true
    }]
  ]
}

然后运行 @babel/cli@7 来转换输入源 src，此命令会将转换后的源输出到 src-mod：

¥And then run @babel/cli@7 to transform the input source src, this command will output the transformed source to src-mod:

npm
Yarn
pnpm
Bun

npx @babel/cli@7 --config-file ./babel.record-tuple-migration.config.json src --out-lib src-mod

yarn dlx @babel/cli@7 --config-file ./babel.record-tuple-migration.config.json src --out-lib src-mod

pnpm dlx @babel/cli@7 --config-file ./babel.record-tuple-migration.config.json src --out-lib src-mod

bun x @babel/cli@7 --config-file ./babel.record-tuple-migration.config.json src --out-lib src-mod

请手动检查 src-mod 是否正确。如果一切正常，请用 src-mod 中的内容覆盖 src。

¥Please manually check whether src-mod is correct. If everything looks good, overwrite src with contents in src-mod.

语法插件

¥Syntax plugins

以下语法插件不再需要，你可以安全地将它们从配置和依赖中移除：

¥The following syntax plugins are no longer needed, you can safely remove them from your configuration and dependencies:

@babel/plugin-syntax-async-functions
@babel/plugin-syntax-async-generators
@babel/plugin-syntax-bigint
@babel/plugin-syntax-class-properties
@babel/plugin-syntax-class-static-block
@babel/plugin-syntax-dynamic-import
@babel/plugin-syntax-exponentiation-operator
@babel/plugin-syntax-export-extensions
@babel/plugin-syntax-export-namespace-from
@babel/plugin-syntax-import-meta
@babel/plugin-syntax-json-strings
@babel/plugin-syntax-logical-assignment-operators
@babel/plugin-syntax-module-string-names
@babel/plugin-syntax-nullish-coalescing-operator
@babel/plugin-syntax-numeric-separator
@babel/plugin-syntax-object-rest-spread
@babel/plugin-syntax-optional-catch-binding
@babel/plugin-syntax-optional-chaining
@babel/plugin-syntax-private-property-in-object
@babel/plugin-syntax-top-level-await
@babel/plugin-syntax-trailing-function-commas
@babel/plugin-syntax-unicode-sets-regex

每个软件包的重大变更

¥Per-package breaking changes

`@babel/core`

使用 browserslist 的 defaults 作为默认编译目标（#12989，#15551）。

¥Use browserslist's defaults as default compilation target (#12989, #15551).

如果你已经在使用 targets 选项或拥有 .browserslistrc 配置文件，则此更改不会影响你。

¥If you are already using the targets option or have a .browserslistrc config file, this change won't affect you.

迁移：你可能可以接受自 browserslist 的 defaults 涵盖了大多数现代浏览器以来的新行为。如果你需要支持旧版浏览器，请创建 .browserslistrc 配置或指定 targets 选项。

¥Migration: You'll probably be fine with the new behavior since the browserslist's defaults covers most modern browsers. If you need to support legacy browsers, create a .browserslistrc config, or specify the targets option.

根 AMD/UMD/SystemJS 选项，即 moduleIds、getModuleId、moduleRoot、moduleId 和 filenameRelative 已移至插件选项（#5473、#12724）。

¥The root AMD/UMD/SystemJS options, namely moduleIds, getModuleId, moduleRoot, moduleId and filenameRelative are moved to plugin options (#5473, #12724).

迁移：将这些选项移至你用于转换模块的插件中。例如，如果你正在使用 @babel/plugin-transform-modules-systemjs：

¥Migration: Move these options to the plugin you are using to transform modules. For example, if you are using @babel/plugin-transform-modules-systemjs:
babel.config.js
```
module.exports = {
  plugins: [
    ['@babel/plugin-transform-modules-systemjs', {
      moduleIds: true,
      moduleRoot: 'myApp',
      getModuleId (name) {
        return name + "suffix";
      },
    }],
  ],
};
```
如果你使用的是 @babel/plugin-transform-modules-amd 或 @babel/plugin-transform-modules-umd，请修改上面的示例。你可以在 Babel 8.0 之前开始迁移。

¥Adapt the example above if you are using @babel/plugin-transform-modules-amd or @babel/plugin-transform-modules-umd. You can start the migration prior to Babel 8.0.

如果你使用 @babel/cli 并从命令行传递 --module-ids、--module-root 和 --module-id，请创建 Babel 配置 babel.config.js 并在其中指定选项。

¥If you are using @babel/cli and passing --module-ids, --module-root and --module-id from command line, please create a Babel config babel.config.js and specify options there.

如果你通过 @babel/preset-env 转换 ESM，则需要明确使用其中一个 @babel/plugin-transform-modules-... 插件。

¥If you are transforming ESM through @babel/preset-env, you will need to explicitly use one of the @babel/plugin-transform-modules-... plugins.
targets.esmodules: true 选项现在的行为与 targets.esmodules: "intersect"（#17188）相同。

¥targets.esmodules: true option now behaves as same as targets.esmodules: "intersect" (#17188)

迁移：在 Babel 7 中，指定 esmodules: true 将覆盖 browsers 目标或 browserslist 的目标，而指定 "intersect" 将与这些目标相交。

¥Migration: In Babel 7, specifying esmodules: true will override the browsers target or browserslist's targets, while specifying "intersect" will intersect with such targets.

如果你的应用针对 2019 年之后发布的现代浏览器，你可以安全地删除 esmodules 选项，因为它们都支持 ES 模块。

¥If your app targets modern browsers released after 2019, you can safely remove the esmodules option as they all support ES modules.

如果你的应用针对 IE 等旧版浏览器，你也可以删除 esmodules 选项，因为 IE 比任何其他浏览器都需要更多的转换。

¥If your app targets legacy browsers such as IE, you can also remove the esmodules option as IE requires more transforms than any other browser.

如果你的应用针对 2019 年之前发布的浏览器，并且你希望保留 Babel 7 esmodules: true 行为，请删除 esmodules 选项并设置以下 browsers 目标：

¥If your app targets browsers released before 2019 and you want to preserve the Babel 7 esmodules: true behavior, remove the esmodules option and set the following browsers target:
babel.config.json
```
{
  "targets": {
    "browsers": "chrome 61, firefox 60, safari 10.1, node 13.2"
  }
}
```
删除 uglify 目标 (#12594)

¥Remove uglify target (#12594)

迁移：uglify 目标自 7.0.0 起已弃用。如果你使用它强制 @babel/preset-env 向下编译为 ES5，并且仍然需要这样做，你可以使用其 forceAllTransforms 选项。

¥Migration: The uglify target had been deprecated since 7.0.0. If you are using it to force @babel/preset-env to transpile down to ES5 and you still need to do so, you can use its forceAllTransforms option.

`@babel/parser`

删除 estree 解析器插件的 classFeatures 选项 (#13752)

¥Remove the estree parser plugin's classFeatures option (#13752)

迁移：从你的配置中删除该选项，因为它现在默认启用。以前，classFeatures 插件使 @babel/parser 能够生成与 ESLint 8 兼容的类属性 AST，遵循 ESTree 规范。在 Babel 8 中，eslint-parser 仅适用于 ESLint 8 及更高版本。

¥Migration: Remove the option from your config, since it's now enabled by default. Previously the classFeatures plugin enables @babel/parser to produce class properties AST compatible with ESLint 8, following the ESTree specification. In Babel 8 the eslint-parser only works with ESLint 8 and above.
删除 decimal 解析器插件 (#16741)

¥Remove the decimal parser plugin (#16741)

迁移：将你的项目迁移到最新提案，并从配置中移除该插件，因为该提案不再包含语法。

¥Migration: Migrate your project to the latest proposal and remove the plugin from your config since the proposal doesn't include syntax anymore.
example.js
```
- 1.03m
+ new Decimal("1.03")
- decimal1 + decimal2
+ decimal1.add(decimal2)
```
删除 importAssertions 解析器插件 (#16770)

¥Remove the importAssertions parser plugin (#16770)

此插件适用于旧版本的导入属性提案，使用 assert 关键字而不是 with。提案在没有 assert 关键字的情况下继续推进。

¥This plugin was for an old version of the import attributes proposal, using the assert keyword instead of with. The proposal moved ahead without the assert keyword.

迁移：如果可能，请在代码中将 assert 替换为 with。如果无法做到这一点，你可以暂时使用 deprecatedImportAssert 解析器插件。

¥Migration: If possible, replace assert with with in your code. If doing so is not possible, you can temporarily use the deprecatedImportAssert parser plugin.
删除 importReflection 解析器插件 (#16808)

¥Remove the importReflection parser plugin (#16808)

"导入反射" 提案不再存在，它被 "源阶段导入" 提案取代，后者使用 source 修饰符进行导入而不是 module。

¥The "import reflection" proposal does not exist anymore, and it was superseeded by the "source phase imports" proposal, which uses the source modifier for imports instead of module.

迁移：用 sourcePhaseImports 替换插件，并迁移代码以在导入声明中使用 source 而不是 module。

¥Migration: Replace the plugin with sourcePhaseImports, and migrate your code to use source instead of module in import declarations.
example.js
```
- import module x from "foo";
+ import source x from "foo";
```

禁止 JSX 属性内的序列表达式(#12447)

¥Disallow sequence expressions inside JSX attributes (#12447)

迁移：查找并替换以下代码模式。你可以在 Babel 8 之前开始迁移：

¥Migration: Find and replace the following code patterns. You can start the migration prior to Babel 8:
input.jsx
```
- <p key={foo, bar}></p> // Invalid
+ <p key={(foo, bar)}></p> // Valid
```
禁止 JSX 文本中出现 {、}、< 和 >(#12451)

¥Disallow {, }, < and > in JSX text (#12451)

迁移：请改用 {'{'}、{'}'}、{'<'} 和 {'>'}。查找并替换以下代码模式。你可以在 Babel 8 之前开始迁移：

¥Migration: Use {'{'}, {'}'}, {'<'} and {'>'} instead. Find and replace the following code patterns. You can start the migration prior to Babel 8:
input.jsx
```
- <p>">" is greater than.</p>
+ <p>"{'>'}" is greater than.</p>
```
注意：从技术上讲，这是一个规范合规性修复，因为 JSX 规范已经禁止了它们。然而，我们选择将其推迟到 Babel 8，因为它可能会破坏某人的代码。

¥Notes: This is technically a spec compliance fix because the JSX specification already forbids them. However, we have chosen to postpone it until Babel 8 because it could break someone's code.

`@babel/generator`

删除 jsonCompatibleStrings 选项 (#9943, #12477)

¥Remove the jsonCompatibleStrings option (#9943, #12477)

迁移：@babel/generator 允许为 jsesc 指定选项，jsesc 是一个用于转义打印值的库。如果你使用的是 jsonCompatibleStrings 选项，则可以将其替换为 jsescOption: { json: true }。

¥Migration: @babel/generator allows to specify options for jsesc, a library used to escape printed values. If you are using the jsonCompatibleStrings option, you can replace it with jsescOption: { json: true }.

在字符串字面量中按原样输出非 ASCII 字符（#12675）

¥Output non-ASCII characters as-is in string literals (#12675)

如果你使用 @babel/cli、webpack、Rollup 或其他 Node.js 打包工具中的任何一个，转换后的代码将始终使用 utf-8 编码，你的应用不会受到影响。仅当你手动调用 babel.transform API 并且你的 Web 服务器未以 utf8 编码提供 js 文件时，此问题才会出现。

¥If you are using any one of @babel/cli, webpack, Rollup, or other Node.js powered bundlers, the transformed code is always encoded with utf-8 and your app will not be affected. The issue only affects if you are manually calling the babel.transform API and your web server is not serving js files in the utf8 encoding.

迁移：确保你的服务器始终以 utf8 编码提供 js 文件。如果无法控制服务器输出，请在 html 文件中指定 script 标记的 charset 属性。

¥Migration: Ensure your server is always serving js files in the utf8 encoding. If you can not control the server output, specify the charset attribute of the script tag in the html files.
```
<script charset="utf-8" src="your-app.js"></script>
```
你也可以通过设置以下设置恢复到 Babel 7 的行为：

¥You can also restore to the Babel 7 behaviour by setting
babel.config.js
```
{
  generatorOpts: {
    jsescOption: {
      minimal: false
    }
  }
}
```

`@babel/preset-env`

注意

@babel/preset-env 的 targets 选项继承了顶层 targets 选项的行为，因此请务必查看 @babel/core 部分。

¥@babel/preset-env's targets option inherits its behavior from the top-level targets option, so make sure to check the @babel/core section.

loose 和 spec 选项已被删除 (#16043)

¥The loose and spec options have been removed (#16043)

迁移：你可以改用 assumptions 顶层选项。请参阅 "从 @babel/preset-env 迁移"loose"and"spec"modes" 了解可立即复制的等效配置。

¥Migration: You can use the assumptions top-level option instead. See "Migrating from @babel/preset-env's "loose" and "spec" modes" for the ready-to-copy equivalent configuration.

includes 和 excludes 尊重重命名的包名称 (#15576)

¥includes and excludes respect renamed package names (#15576)

迁移：如果 includes 或 excludes 包含包重命名部分中提到的任何插件，请将其更改为新名称。例如，

¥Migration: If includes or excludes contain any plugins mentioned in the Packages Renames section, change it to the new name. For example,
babel.config.json
```
{
  "presets": [[
    "@babel/preset-env",
    {
-     "includes": ["proposal-optional-chaining"]
+     "includes": ["transform-optional-chaining"]
    }
  ]]
}
```

默认启用 bugfixes 选项 (#13866)

¥Enable the bugfixes option by default (#13866)

迁移：你可能会对新行为感到满意，因为 Babel 现在尝试将损坏的语法编译为目标浏览器支持的最接近的未损坏的现代语法。如果无论如何你想恢复 Babel 7 的行为，你可以指定 bugfixes: false。

¥Migration: You will probably be fine with the new behaviour as Babel now tries to compile the broken syntax to the closest non-broken modern syntax supported by your target browsers. If anyhow you want to restore the Babel 7 behaviour, you can specify bugfixes: false.
删除的语法插件不能在 includes 和 excludes（#15810）中使用

¥Removed syntax plugins can not be used in includes and excludes (#15810)

迁移：如果你使用 includes 和 excludes 选项中的任何上面列出的语法插件，则可以安全地删除它们。

¥Migration: You can safely remove them if you are using any of syntax plugins listed above in the includes and excludes options.

`@babel/preset-react` 和 `@babel/plugin-transform-react-jsx`

¥@babel/preset-react and @babel/plugin-transform-react-jsx

注意

@babel/parser 还包含一些与 JSX 相关的重大变更，因此请务必查看 @babel/parser 部分。

¥@babel/parser also includes some JSX-related breaking changes, so make sure to check the @babel/parser section.

默认使用新的 JSX 实现(#12630)

¥Use the new JSX implementation by default (#12630)

迁移：如果你使用的是 React 或 Preact 的现代版本，它应该无需任何配置更改即可工作。否则，你可以将 runtime: "classic" 选项传递给 @babel/preset-react 或 @babel/plugin-transform-react-jsx，以明确你对 createElement（或其他库中的等效函数）的使用。

¥Migration: If you are using a modern version of React or Preact, it should work without any configuration changes. Otherwise, you can pass the runtime: "classic" option to @babel/preset-react or @babel/plugin-transform-react-jsx to be explicit about your usage of createElement (or the equivalent function in other libraries).
将 development 选项设置为已配置环境（#16927）的默认选项。

¥Make the development option default to the configured environment (#16927)

请注意，通过 envName 选项设置的 Babel 环境默认为 process.env.BABEL_ENV || process.env.NODE_ENV || "development"：如果你未指定 envName 选项，也未指定 BABEL_ENV 或 NODE_ENV 环境变量，则默认为 development。

¥Note that Babel's environment, set through envName option, defaults to process.env.BABEL_ENV || process.env.NODE_ENV || "development": if you don't specify neither the envName option nor the BABEL_ENV or NODE_ENV environment variables, it will default to development.

迁移：在生产版本中，将 BABEL_ENV 或 NODE_ENV 环境变量（或 envName Babel 选项）设置为 "production"。如果你只想在生产模式下运行此预设，则可以将 development 选项明确设置为 false。

¥Migration: In production builds, set the BABEL_ENV or NODE_ENV environment variables, or the envName Babel option, to "production". If you want to run only this preset in production mode, then you can explicitly set the development option to false.

删除 useSpread 和 useBuiltIns 选项 (#12593)

¥Remove useSpread and useBuiltIns options (#12593)

迁移：Babel 8 总是将 JSX spread 元素编译为 object spread：

¥Migration: Babel 8 always compiles JSX spread elements to object spread:
input.jsx
```
<div {...props}></div>
// transforms to
jsx("div", { ...props })
```
如果你的应用面向 2019 年之后发布的现代浏览器，你可以安全地删除这些选项，因为对象传播的代码占用量更少。

¥If your app targets to modern browsers released after 2019, you can safely remove these options as object spread has less code footprint.

如果你的代码需要在不支持对象传播的环境中运行，你可以使用 @babel/preset-env（推荐）或 @babel/plugin-transform-object-rest-spread。如果你想向下转译 Object.assign，你还需要启用 @babel/plugin-transform-object-assign。

¥If your code needs to run in an environment which doesn't support object spread, you can either use @babel/preset-env (recommended) or @babel/plugin-transform-object-rest-spread. If you want to transpile Object.assign down, you also need to enable @babel/plugin-transform-object-assign.

在 Babel 7.7.0 中，你可以使用 useSpread: true 选项选择启用 Babel 8 的行为。

¥In Babel 7.7.0, you can opt into the Babel 8 behavior by using the useSpread: true option.
类型检查输入选项 (#12460)

¥Type check input options (#12460)

迁移：该预设还将报告无效的选项名称。请参阅 docs 并确保有效使用。

¥Migration: The preset will also report invalid option names. Refer to the docs and ensure valid usage.

在自动运行时禁止 filter 选项 (#15068)

¥Disallow filter option in automatic runtime (#15068)

迁移：filter 选项只能与 classic 运行时一起使用。如果你已切换到 automatic 运行时，则可以安全地删除此选项。否则请指定 runtime: "classic"。

¥Migration: The filter option can only be used with the classic runtime. If you have switched to automatic runtime, you can safely remove this option. Otherwise please specify runtime: "classic".

`@babel/preset-typescript`

注意

请确保同时检查 @babel/plugin-transform-typescript 的变更，因为这是此预设在底层使用的内容。

¥Make sure to also check the @babel/plugin-transform-typescript changes changes, since it's what this preset uses under the hood.

删除 isTSX 和 allExtensions 选项 (#14955)

¥Remove isTSX and allExtensions options (#14955)

迁移：

¥Migration:
- isTSX: true 和 allExtensions: true
  
  ¥isTSX: true and allExtensions: true
  
  如果你已经在使用 @babel/preset-react、@babel/plugin-transform-react-jsx 或任何其他第三方 jsx 预设（例如 @vue/babel-preset-jsx），并且想要转译 .tsx 文件，则可以安全地删除这两个选项。Babel 8 将使用此预设和其他 JSX 插件自动处理 .tsx 文件。
  
  ¥If you are already using @babel/preset-react, @babel/plugin-transform-react-jsx or any other third-party jsx presets such as @vue/babel-preset-jsx, and you want to transpile .tsx files, you can safely remove these two options. Babel 8 will automatically handle .tsx files using this preset and the other JSX plugin.
  babel.config.json
```
{
  "presets": [
    ["@babel/preset-react", { "runtime": "automatic" }],
-   ["@babel/preset-typescript", { "allExtensions": true, "isTSX": true }]
+   ["@babel/preset-typescript"]
  ]
}
```
  如果要转译 .tsx 以外的文件，例如 .vue，请使用 ignoreExtensions: true：
  
  ¥If you want to transpile files other than .tsx, such as .vue, use ignoreExtensions: true:
  babel.config.js
```
{
  overrides: [{
    include: /\.vue$/,
    presets: [
      ['@babel/preset-typescript', {
-       allExtensions: true, isTSX: true
+       ignoreExtensions: true
      }]
    ]
  }]
}
```
  如果你想保留 JSX 格式但转译 TypeScript 部分，请使用 ignoreExtensions: true 并启用 @babel/plugin-syntax-jsx 插件。
  
  ¥If you want to preserve the JSX format but transpile the TypeScript part, use ignoreExtensions: true and enable the @babel/plugin-syntax-jsx plugin.
- isTSX: false 和 allExtensions: true
  
  ¥isTSX: false and allExtensions: true
  
  使用 ignoreExtensions: true，参见上面的示例。
  
  ¥Use ignoreExtensions: true, see the example above.
- isTSX: false 和 allExtensions: false
  
  ¥isTSX: false and allExtensions: false
  
  你可以安全地删除它们。
  
  ¥You can safely remove them.

删除 allowDeclareFields 选项 (#12461)

¥Remove allowDeclareFields option (#12461)

迁移：从你的配置中删除该选项，因为它现在默认启用。

¥Migration: Remove the option from your config, since it's now enabled by default.
类型检查输入选项 (#12460)

¥Type check input options (#12460)

迁移：该预设还将报告无效的选项名称。请参阅 docs 并确保有效使用。例如，runtime 不是有效的 preset-typescript 选项，因此应删除。

¥Migration: The preset will also report invalid option names. Refer to the docs and ensure valid usage. For example, runtime is not a valid preset-typescript option and thus should be removed.

`@babel/plugin-transform-typescript`

保留未初始化的类字段(#12461)

¥Preserve uninitialized class fields (#12461)

迁移：如果你不想将字段初始化为 undefined，请使用 TypeScript 3.7 中引入的 declare 语法：

¥Migration: If you don't want fields to be initialized to undefined use the declare syntax, introduced in TypeScript 3.7:
input.ts
```
class A {
  foo: string | void; // initialized to undefined
  declare bar: number; // type-only, will be removed
}
```

删除 allowDeclareFields 选项 (#12461)

¥Remove allowDeclareFields option (#12461)

迁移：从你的配置中删除该选项，因为它现在默认启用。

¥Migration: Remove the option from your config, since it's now enabled by default.

`@babel/plugin-syntax-typescript`

删除 isTSX 选项 (#14955)

¥Remove isTSX option (#14955)

迁移：如果你正在使用 isTSX: true，请删除此选项并启用 @babel/plugin-syntax-jsx 插件：

¥Migration: If you are using isTSX: true, remove this option and enable the @babel/plugin-syntax-jsx plugin:
```
{
  "plugins": [
-   ["@babel/plugin-syntax-typescript", { "isTSX": true }]
+   "@babel/plugin-syntax-typescript",
+   "@babel/plugin-syntax-jsx"
  ]
}
```
如果你正在使用 isTSX: false，你可以安全地将其删除。

¥If you are using isTSX: false, you can safely remove it.

`@babel/preset-flow`

注意

请确保同时检查 @babel/plugin-transform-flow-strip-types 的变更，因为这是此预设在底层使用的内容。

¥Make sure to also check the @babel/plugin-transform-flow-strip-types changes, since it's what this preset uses under the hood.

类型检查输入选项 (#12460)

¥Type check input options (#12460)

迁移：该预设还将报告无效的选项名称。请参阅 docs 并确保有效使用。

¥Migration: The preset will also report invalid option names. Refer to the docs and ensure valid usage.
移除 allowDeclareFields 和 enums 选项 (#12457、#16792)

¥Remove the allowDeclareFields and enums options (#12457, #16792)

迁移：请从你的配置中删除这些选项，因为它们现在默认启用。

¥Migration: Remove these options from your config, since they are now enabled by default.

`@babel/plugin-transform-flow-strip-types`

保留未初始化的类字段(#12457)

¥Preserve uninitialized class fields (#12457)

迁移：如果你不希望字段初始化为 undefined，请使用 Flow 0.120 中引入的新 declare 语法：

¥Migration: Use the new declare syntax, introduced in Flow 0.120, if you don't want fields to be initialized to undefined:
input.js
```
class A {
  foo: string | void; // initialized to undefined
  declare bar: number; // type-only, will be removed
}
```

移除 allowDeclareFields 和 enums 选项 (#12457、#16792)

¥Remove the allowDeclareFields and enums options (#12457, #16792)

迁移：请从你的配置中删除这些选项，因为它们现在默认启用。

¥Migration: Remove these options from your config, since they are now enabled by default.

`@babel/plugin-transform-runtime`

corejs 选项已被删除 (#16311)

¥The corejs option has been removed (#16311)

迁移：要注入 polyfill，可以直接使用 babel-plugin-polyfill-corejs3 或已弃用的 babel-plugin-polyfill-corejs2。

¥Migration: To inject polyfills, you can use babel-plugin-polyfill-corejs3 or the deprecated babel-plugin-polyfill-corejs2 directly.

useESModules 选项已被删除 (#16141)

¥The useESModules option has been removed (#16141)

迁移：从你的配置中删除它。@babel/runtime 现在将在需要时使用 package.json#exports 自动公开 ES 模块。

¥Migration: Delete it from your configuration. @babel/runtime will now automatically expose ES modules when needed, using package.json#exports.
runtime 和 helpers 选项已被删除 (#16311)

¥The runtime and helpers options have been removed (#16311)

迁移：从你的配置中删除它们：@babel/runtime 现在将始终导入助手。如果你不想将导入注入到辅助程序中，请从你的配置中删除 @babel/plugin-transform-runtime。

¥Migration: Delete them from your configuration: @babel/runtime will now always import helpers. If you don't want to inject imports to helpers, remove @babel/plugin-transform-runtime from your config.

`@babel/plugin-transform-modules-systemjs`

将 import() 转换为 SystemJS 时需要 @babel/plugin-transform-dynamic-import(#12700)

¥Require @babel/plugin-transform-dynamic-import when transforming import() to SystemJS (#12700)

迁移：将 @babel/plugin-transform-dynamic-import 添加到你的配置中：你已经可以在 Babel 7 中做到这一点了。如果你使用的是 @babel/preset-env，则无需执行任何操作。

¥Migration: Add @babel/plugin-transform-dynamic-import to your config: you can already do it in Babel 7. If you are using @babel/preset-env, you don't need to do anything.
babel.config.js.diff
```
{
  "plugins": [
+   "@babel/plugin-transform-dynamic-import",
    "@babel/plugin-transform-modules-systemjs",
  ]
}
```
注意：自引入以来，所有其他支持动态导入的插件（transform-modules-commonjs 和 transform-modules-amd）都需要单独的插件。我们无法为 transform-modules-systemjs 更改它，因为该包确实已经支持动态导入。

¥Notes: All the other plugins which support dynamic import (transform-modules-commonjs and transform-modules-amd) require the separate plugin since it was introduced. We couldn't change it for transform-modules-systemjs because that package did already support dynamic import.

`@babel/plugin-transform-regenerator`

不要替换全局 regeneratorRuntime 引用（#17237）。

¥Do not replace global regeneratorRuntime references (#17237)

Babel 7 过去常用 Babel 的 regeneratorRuntime 辅助函数替换对 regeneratorRuntime 全局变量的引用：

¥Babel 7 used to replace references to a regeneratorRuntime global with Babel's regeneratorRuntime helper:
input.js
```
console.log(regeneratorRuntime.isGeneratorFunction(fn));
```
output.js
```
import _regeneratorRuntime from "@babel/runtime/regenerator";
console.log(_regeneratorRuntime.isGeneratorFunction(fn));
```
在 Babel 8 中，这种情况不会再发生。

¥This doesn't happen anymore in Babel 8.

迁移：建议的方法是更新你的代码，使其不再依赖不存在的 regeneratorRuntime 全局变量。如果无法做到这一点，你可以在应用入口点导入未维护的 regenerator-runtime 包，这将定义 regeneratorRuntime 全局变量，或者使用 babel-plugin-polyfill-regenerator 自动为你注入该导入。

¥Migration: The recommended approach is to update your code to not rely on a non-existent regeneratorRuntime global. If that's not possible, you can either import the unmaintained regenerator-runtime package in your application entrypoint, which will define the regeneratorRuntime global, or use babel-plugin-polyfill-regenerator to automatically inject that import for you.

`@babel/plugin-proposal-decorators`

仅支持该提案的 legacy 和 2023-11 版本。此外，该插件现在需要 version 选项 (#12712, #15676)。

¥Only support the legacy and 2023-11 versions of the proposal. In addition to that, the plugin now requires a version option (#12712, #15676)

迁移：你应该迁移到最新版本的提案和 "2023-11"。

¥Migration: You should migrate to the latest version of the proposal, "2023-11".
babel.config.json
```
{
  "plugins": [
    ["@babel/plugin-proposal-decorators", {
-     "decoratorsBeforeExport": true,
-     "version": "2018-09",
+     "version": "2023-11"
    }]
  ]
}
```
语法是相同的，但你需要重写装饰器函数。规范存储库提供了最新版本与 2018-09 版本对比。从 Babel 7.22.0 开始，你已经可以使用 @babel/plugin-proposal-decorators 的 "version": "2023-11" 选项进行迁移。

¥The syntax is the same, but you will need to rewrite your decorator functions. The spec repo provides comparison between the latest version and the 2018-09 version. You can already migrate since Babel 7.22.0, using the "version": "2023-11" option of @babel/plugin-proposal-decorators.

虽然 Babel 8 仍然支持 legacy 版本，但建议迁移到 2023-11 版本，无论：Babel 8 和 TypeScript 5.0 都支持 2023-11 版本，而 Babel 和 tsc 的实现之间的 legacy 版本中存在一些行为差异。浏览器将仅实现该提案的最新版本。

¥Although Babel 8 still supports the legacy version, it is advisable to migrate to the 2023-11 version regardless: both Babel 8 and TypeScript 5.0 support the 2023-11 version, while there are a few behaviour differences in the legacy version between Babel and tsc's implementation. Browsers will only implement the latest version of the proposal.

`@babel/eslint-parser`

删除 allowImportExportEverywhere 选项 (#13921)

¥Remove allowImportExportEverywhere option (#13921)

迁移：请改用 babelOptions.parserOpts.allowImportExportEverywhere。

¥Migration: Use babelOptions.parserOpts.allowImportExportEverywhere instead.
.eslintrc
```
{
  "parser": "@babel/eslint-parser",
  "parserOptions": {
-   "allowImportExportEverywhere": true,
+   "babelOptions": {
+     "parserOpts": {
+       "allowImportExportEverywhere": true
+     }
+   }
  }
}
```

parserOpts.allowSuperOutsideMethod 默认为 false (#13921)

¥parserOpts.allowSuperOutsideMethod defaults to false (#13921)

迁移：如果你想恢复 Babel 7 的行为，请将 babelOptions.parserOpts.allowSuperOutsideMethod 设置为 true。

¥Migration: If you want to restore to Babel 7 behaviour, set babelOptions.parserOpts.allowSuperOutsideMethod to true.
allowReturnOutsideFunction 是从 ecmaFeatures.globalReturn (#13921) 推断出来的

¥allowReturnOutsideFunction is inferred from ecmaFeatures.globalReturn (#13921)

迁移：如果要启用 allowReturnOutsideFunction，请将 ecmaFeatures.globalReturn 设置为 true。

¥Migration: If you want to enable allowReturnOutsideFunction, set ecmaFeatures.globalReturn to true.
.eslintrc
```
{
  "parser": "@babel/eslint-parser",
  "parserOptions": {
    "ecmaFeatures": {
      "globalReturn": true
    }
  }
}
```

`@babel/node`

-gc 和 -d 命令行标志已被删除 (#15956) 迁移：分别使用 --expose-gc 和 --inspect Node.js 标志。请注意，虽然 -d 是 --debug 的缩写，但后者却是自 Node.js 7.7.0 起已弃用。

¥The -gc and -d command-line flags have been removed (#15956) Migration: Use the --expose-gc and --inspect Node.js flags respectively. Note that although -d was short for --debug, the latter has been deprecated since Node.js 7.7.0.
Node.js 和 Babel 的命令行标志现在必须在文件名之前传递，而脚本本身的标志必须在文件名之后传递。(#16706):

¥Command-line flags for Node.js and Babel must now be passed before the filename, while flags for the script itself must be passed after. (#16706):
```
babel-node --flag-for-node --flag-for-babel script.js --flag-for-script
```

准备工作​

Babel​

Node.js 支持​

仅限 ESM​

对等依赖要求​

重命名的软件包​

已停用的软件包​

@babel/runtime-corejs2​

@babel/plugin-syntax-import-assertions​

@babel/plugin-proposal-record-and-tuple​

语法插件​

每个软件包的重大变更​

@babel/core​

@babel/parser​

@babel/generator​

@babel/preset-env​

@babel/preset-react 和 @babel/plugin-transform-react-jsx​

@babel/preset-typescript​

@babel/plugin-transform-typescript​

@babel/plugin-syntax-typescript​

@babel/preset-flow​

@babel/plugin-transform-flow-strip-types​

@babel/plugin-transform-runtime​

@babel/plugin-transform-modules-systemjs​

@babel/plugin-transform-regenerator​

@babel/plugin-proposal-decorators​

@babel/eslint-parser​

@babel/node​