升级到 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 迁移指南。

准备中

🌐 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 旁边）。
如果你使用 @babel/preset-env，请启用它的 bugfixes 选项。
如果你使用 @babel/preset-env 的 loose 或 spec 选项，迁移到 assumptions。如果你在单独的插件中使用 loose 或 spec，也可以考虑迁移，尽管它们在 Babel 8 中仍然可用。
如果你使用 @babel/preset-react 或 @babel/plugin-transform-react-jsx，请明确设置它们的 runtime 选项（Babel 7 默认是 "classic"，Babel 8 默认是 "automatic"）。如果你继续使用经典运行时，请将 useSpread 选项设置为 true。
如果你使用 TypeScript 或 Flow 预设，请将 isTSX 和 allExtensions 选项替换为 ignoreExtensions。
如果你正在转换 TypeScript 或 Flow，把 allowDeclareFields 选项设置为 true（参见 TypeScript）。
如果你使用了 @babel/plugin-transform-runtime 的 corejs 或 @babel/preset-env 的 useBuiltIns 选项，把它们去掉，改用 babel-plugin-polyfill-corejs3 就行了。
如果你使用 @babel/plugin-proposal-decorators，请将它的 version 选项设置为 legacy 或 2023-11。
如果你在使用的话，就把 @babel/plugin-proposal-record-and-tuple 和 @babel/plugin-syntax-import-assertions 插件删掉。

Babel

🌐 All of Babel

Node.js 支持

🌐 Node.js support

所有 Babel 8 的包都需要 Node.js ^22.18.0 || >=24.11.0。我们强烈建议你使用 Node.js 的 Active LTS 版本（v24）：更多信息请参见 nodejs/Release。

🌐 All Babel 8 packages require Node.js ^22.18.0 || >=24.11.0. We highly encourage you to use the Active LTS version of Node.js (v24): see nodejs/Release for more information.

这只是意味着 Babel 本身不能在旧版本的 Node 上运行。它仍然可以输出可以在旧 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, #17943)。

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

同伴依赖要求

🌐 Peer dependency requirements

所有预设和插件都需要 @babel/core@^8.0.0 作为同伴依赖。有些 Babel 7 的插件和预设可能可以与 @babel/core@8 配合使用，有些 Babel 8 的插件和预设可能可以与 @babel/core@7 配合使用，但我们对这些不提供任何官方支持。
@babel/eslint-parser 和 @babel/eslint-plugin 需要 eslint@>=9.0.0 作为同级依赖。(#15563)

`loose` 和 `spec` 选项的弃用

🌐 loose and spec options deprecation

loose 和 spec 选项已经被移除了，取而代之的是新的 assumptions 顶层选项，它更灵活，可以用来为你的整个代码库中所有插件统一配置特定的假设。

🌐 The loose and spec options have been removed in favor of the new assumptions top-level option, which is more flexible and can be used to configure assumptions specific to your codebase for all plugins in a single place.

它们已经从 @babel/preset-env 中完全移除了，你可以把相应的 assumptions 配置复制到你的配置里。
在单独的插件中使用时，它们仍然可以工作，但会发出一个警告，指向相应的 assumptions 配置。升级到 Babel 8 后，你可以迁移它们。

已重命名的软件包

🌐 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-modules`	`@babel/plugin-transform-json-modules`
`@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。

请升级到 babel-plugin-polyfill-corejs3。安装新运行时后，请将 corejs 版本设置为你正在使用的 core-js 版本。

🌐 Please upgrade to babel-plugin-polyfill-corejs3. 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`

这个提案演变成了 import attributes，现在 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-import-attributes-to-assertions`

这个插件会将标准的导入属性 with { type: "json" } 转换为旧版形式 assert { type: "json" }，这种形式只被过时的 Chrome (91-122) 和 Node.js 18 支持。如果你的编译目标不包含这些版本，你可以放心地移除这个插件。

🌐 This plugin transforms the standard import attributes with { type: "json" } to the legacy form assert { type: "json" }, which is supported only by obsolete Chrome (91-122) and Node.js 18. You can safely remove this plugin if your compilation targets does not include those versions.

`@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.

`@babel/plugin-transform-object-assign`

这是一个老旧的 polyfill 插件，现在已经过时了。

🌐 This is a legacy polyfill plugin, and it is now outdated.

如果你正在使用这个插件来填充 Object.assign，请改用 babel-plugin-polyfill-corejs3。

🌐 If you are using this plugin to polyfill Object.assign, please use babel-plugin-polyfill-corejs3 instead.

`@babel/plugin-transform-object-set-prototype-of-to-assign`

这个插件不再维护了。如果你正在使用这个插件来 polyfill Object.setPrototypeOf，请改用 babel-plugin-polyfill-corejs3 。

🌐 This plugin is not maintained anymore. If you are using this plugin to polyfill Object.setPrototypeOf, please use babel-plugin-polyfill-corejs3 instead.

`@babel/plugin-transform-react-compat`

这是针对 React v0.x 的，它早已被废弃，不再维护。

🌐 This is for React v0.x, which has been long deprecated and is no longer maintained.

`@babel/plugin-transform-react-{source,self}`

如果使用 React v19 或更高版本，你可以安全地移除这两个插件。对于使用 React v18 或更早版本的用户，请移除它们并改用 @babel/plugin-transform-react-jsx-development，因为它们现在已经包含在开发插件中了。

🌐 You can safely remove these two plugins if using React v19 or later. For users of React v18 or earlier, please remove them and use @babel/plugin-transform-react-jsx-development instead, as they are now included in the development plugin.

babel.config.json
  {
    "plugins": [
-     "@babel/plugin-transform-react-source",
-     "@babel/plugin-transform-react-self"
+     "@babel/plugin-transform-react-jsx-development"
    ]
  }

`@babel/plugin-transform-property-mutators`

属性修改器无法被转换，这个插件没用。

🌐 Property mutators cannot be transformed, this plugin is useless.

语法插件

🌐 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)。

如果你已经在使用 targets 选项或者有一个 .browserslistrc 配置文件，这个更改不会影响你。

迁移：你可能对新的行为没什么问题，因为browserslist 的 defaults 覆盖了大多数现代浏览器。如果你需要支持旧版浏览器，可以创建一个.browserslistrc 配置，或者指定targets 选项。

根级 AMD/UMD/SystemJS 选项，即 moduleIds、getModuleId、moduleRoot、moduleId 和 filenameRelative 已经移到插件选项中 (#5473, #12724)。

迁移：将这些选项移到你用来转换模块的插件中。例如，如果你使用的是 @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";
      },
    }],
  ],
};
```
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 并在那里指定选项。

如果你通过 @babel/preset-env 转换 ESM，你将需要明确使用其中一个 @babel/plugin-transform-modules-... 插件。
targets.esmodules: true 选项现在的行为与 targets.esmodules: "intersect" 相同 (#17188)

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

如果你的应用面向2019年之后发布的现代浏览器，你可以放心地移除 esmodules 选项，因为它们都支持 ES 模块。

如果你的应用面向像 IE 这样的老浏览器，你也可以移除 esmodules 选项，因为 IE 需要的转换比其他任何浏览器都多。

如果你的应用面向的是2019年前发布的浏览器，并且你想保留 Babel 7 esmodules: true 的行为，请删除 esmodules 选项并设置以下 browsers 目标：
babel.config.json
```
{
  "targets": {
    "browsers": "chrome 61, firefox 60, safari 10.1, node 13.2"
  }
}
```
移除 uglify 目标 (#12594)

迁移：uglify 目标从 7.0.0 开始已被弃用。如果你使用它来强制 @babel/preset-env 转译到 ES5，并且仍然需要这样做，你可以使用它的 forceAllTransforms 选项。

`@babel/parser`

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

迁移：从你的配置中移除这个选项，因为它现在默认已启用。之前 classFeatures 插件启用 @babel/parser 来生成与 ESLint 8 兼容的类属性 AST，遵循 ESTree 规范。在 Babel 8 中，eslint-parser 仅适用于 ESLint 8 及以上版本。
移除 decimal 解析器插件 (#16741)

迁移：将你的项目迁移到最新的提案，并从配置中移除该插件，因为该提案已经不再包含语法了。
example.js
```
- 1.03m
+ new Decimal("1.03")
- decimal1 + decimal2
+ decimal1.add(decimal2)
```
移除 importAssertions 和 deprecatedImportAssert 解析器插件 (#16770, #17603)

这些插件是针对旧版本的导入属性提案的，使用的是 assert 关键字而不是 with。这个提案在没有 assert 关键字的情况下推进了。
移除 importReflection 解析器插件 (#16808)

“import reflection” 提案已经不存在了，它被“source phase imports” 提案取代了，后者在导入时使用 source 修饰符，而不是 module。

迁移：将插件替换为 sourcePhaseImports，并将你的代码迁移，以在导入声明中使用 source 替代 module。
example.js
```
- import module x from "foo";
+ import source x from "foo";
```

禁止在 JSX 属性中使用序列表达式 (#12447)

迁移：查找并替换以下代码模式。你可以在 Babel 8 之前开始迁移：
input.jsx
```
- <p key={foo, bar}></p> // Invalid
+ <p key={(foo, bar)}></p> // Valid
```
在 JSX 文本中禁止使用 {、}、< 和 > (#12451)

迁移：改用 {'{'}、{'}'}、{'<'} 和 {'>'}。查找并替换以下代码模式。你可以在 Babel 8 之前就开始迁移：
input.jsx
```
- <p>">" is greater than.</p>
+ <p>"{'>'}" is greater than.</p>
```
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)

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

在字符串字面量中原样输出非 ASCII 字符 (#12675)

如果你正在使用 @babel/cli、webpack、Rollup 或其他基于 Node.js 的打包工具，转换后的代码总是以 utf-8 编码，你的应用不会受到影响。这个问题只会在你手动调用 babel.transform API 并且你的网页服务器没有以 utf8 编码提供 js 文件时才会发生。

迁移：确保你的服务器始终以 utf8 编码提供 js 文件。如果你无法控制服务器输出，请在 html 文件中的 script 标签中指定 charset 属性。
```
<script charset="utf-8" src="your-app.js"></script>
```
You can also restore to the Babel 7 behaviour by setting
babel.config.js
```
{
  generatorOpts: {
    jsescOption: {
      minimal: false
    }
  }
}
```

`@babel/preset-env`

note

@babel/preset-env 的 targets 选项继承了顶层 targets 选项的行为，所以记得查看 @babel/core 部分。

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

迁移：你可以改用 assumptions 顶层选项。查看从 @babel/preset-env 的 “loose” 和 “spec” 模式迁移获取可直接复制的等效配置。
corejs 选项必须指定 core-js 3 的次要版本 (#16095)

在 Babel 7 中，推荐的 corejs 选项是 corejs: 3。不过，这个选项意味着 Babel 使用的是 corejs: "3.0" 中可用的特性，而 corejs: "3.0" 发布于 2019 年，缺少很多最新的 ECMAScript 特性。

迁移：指定你使用的 core-js 3 的小版本，以确保在需要时最新功能会被 polyfill。例如，
```
import corejsPackage from "core-js/package.json" with { type: "json" }
export default {
  "presets": [[
    "@babel/preset-env",
    {
      "corejs": corejsPackage.version
    }
  ]]
}
```
如果你正在编写一个依赖 core-js 的库，最佳的 corejs 版本应该是你库的 package.json 的 dependencies 中可用的第一个版本。

modules: "auto" 默认假设支持 ESM，而不是不支持 (#18069)

如果你是通过其他工具使用 Babel，比如 Webpack 或 Rollup，这个改变不会影响你，因为它们已经告诉 Babel 它们支持 ESM。

迁移：如果你需要转译为 CommonJS，可以将 modules: "commonjs" 选项传给 @babel/preset-env，或者使用 @babel/plugin-transform-commonjs 插件。
include 和 exclude 尊重已重命名的包名 (#15576)

迁移：如果 include 或 exclude 包含包重命名部分中提到的任何插件，请将其更改为新名称。例如，
babel.config.json
```
{
  "presets": [[
    "@babel/preset-env",
    {
-     "include": ["proposal-optional-chaining"]
+     "include": ["transform-optional-chaining"]
    }
  ]]
}
```

bugfixes 选项已被移除 (#13866, #17078)

迁移：你可能没问题，因为 Babel 现在会尝试将错误的语法编译成你的目标浏览器支持的最接近的_非错误现代语法_。

如果你无论如何想为了调试目的恢复 Babel 7 的行为，你可以指定 exclude 选项：{ exclude: ["bugfix/.+"] } 来显式排除修复漏洞的插件。注意，这样做会增加输出体积，因为 Babel 必须编译那些如果不是某些特定漏洞，本来你的目标环境通常已经支持的特性。
已移除的语法插件不能在 include 和 exclude 中使用 (#15810)

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

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

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

note

@babel/parser 也包括一些与 JSX 相关的不兼容更改，所以一定要查看 @babel/parser 部分。

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

迁移：如果你使用的是现代版本的 React 或 Preact，它应该可以在无需任何配置更改的情况下工作。否则，你可以将 runtime: "classic" 选项传递给 @babel/preset-react 或 @babel/plugin-transform-react-jsx，以明确表示你使用了 createElement（或其他库中的等效函数）。
将 development 选项默认设置为已配置的环境 (#16927)

请注意，Babel 的环境是通过 envName 选项设置的，默认值为 process.env.BABEL_ENV || process.env.NODE_ENV || "development"：如果你既没有指定 envName 选项，也没有设置 BABEL_ENV 或 NODE_ENV 环境变量，它将默认使用 development。

迁移：在生产构建中，设置 BABEL_ENV 或 NODE_ENV 环境变量，或者将 envName Babel 选项设置为 "production"。如果你只想在生产模式下运行 这个预设，那么可以显式地将 development 选项设置为 false。

移除 useSpread 和 useBuiltIns 选项 (#12593)

迁移：Babel 8 总是将 JSX 扩展元素编译为对象扩展：
input.jsx
```
<div {...props}></div>
// transforms to
jsx("div", { ...props })
```
如果你的应用面向 2019 年之后发布的现代浏览器，你可以安全地删除这些选项，因为对象传播的代码占用量更少。

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

在 Babel 7.7.0 中，你可以通过使用 useSpread: true 选项选择 Babel 8 的行为。
类型检查输入选项 (#12460)

迁移：该预设还会报告无效的选项名称。请参考文档并确保正确使用。
默认情况下在开发模式中停止生成 __source 和 __self (#17571)

React 19.2 从 jsxDEV 中移除了 source 和 self 参数。Babel 8 在开发模式下调用 jsxDEV 时不再传递它们。

迁移：如果你使用的是 React 19.2 或更高版本，你无需做任何操作。如果你使用的是较旧的 React 版本或仍然需要这些参数的自定义 JSX 运行时，请在预设中将 developmentSourceSelf 设置为 true，或者在 @babel/plugin-transform-react-jsx-development 中将 sourceSelf 设置为 true：
babel.config.json
```
  {
    "presets": [
-     ["@babel/preset-react", { "development": true }]
+     ["@babel/preset-react", { "development": true, "developmentSourceSelf": true }]
    ]
  }
```
babel.config.json
```
{
  "plugins": [
-     "@babel/plugin-transform-react-jsx-development",
+     ["@babel/plugin-transform-react-jsx-development", { "sourceSelf": true }]
  ]
}
```

在自动运行时不允许使用 filter 选项 (#15068)

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

`@babel/preset-typescript`

note

也别忘了查看 @babel/plugin-transform-typescript 的更改，因为这是这个预设在底层使用的插件。

移除 isTSX 和 allExtensions 选项 (#14955)

迁移：
- isTSX: true 和 allExtensions: true
  
  如果你已经在使用 @babel/preset-react、@babel/plugin-transform-react-jsx 或任何其他第三方 jsx 预设，比如 @vue/babel-preset-jsx，并且你想要转译 .tsx 文件，你可以放心地移除这两个选项。Babel 8 会自动使用这个预设和其他 JSX 插件来处理 .tsx 文件。
  babel.config.json
```
{
  "presets": [
    ["@babel/preset-react", { "runtime": "automatic" }],
-   ["@babel/preset-typescript", { "allExtensions": true, "isTSX": true }]
+   ["@babel/preset-typescript"]
  ]
}
```
  如果你想转译除了 .tsx 之外的文件，比如 .vue，可以用 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 插件。
- isTSX: false 和 allExtensions: true
  
  使用 ignoreExtensions: true，参见上面的例子。
- isTSX: false 和 allExtensions: false
  
  你可以安全地删除它们。

移除 allowDeclareFields 选项 (#12461)

迁移：从你的配置中移除该选项，因为它现在默认已启用。
类型检查输入选项 (#12460)

迁移：该预设还会报告无效的选项名称。请参考文档并确保正确使用。例如，runtime 不是有效的 preset-typescript 选项，因此应该将其移除。
onlyRemoveTypeImports 默认是 true (#12460)

迁移：如果你使用的 TypeScript 版本低于 3.8，或者在 TSConfig 中没有将 verbatimModuleSyntax 设置为 true，请指定 onlyRemoveTypeImports: false。

`@babel/plugin-transform-typescript`

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

迁移：如果你不希望字段被初始化为 undefined，可以使用在 TypeScript 3.7 中引入的 declare 语法：
input.ts
```
class A {
  foo: string | void; // initialized to undefined
  declare bar: number; // type-only, will be removed
}
```

移除 allowDeclareFields 选项 (#12461)

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

`@babel/plugin-syntax-typescript`

移除 isTSX 选项 (#14955)

迁移：如果你正在使用 isTSX: true，请移除此选项并启用 @babel/plugin-syntax-jsx 插件：
```
{
  "plugins": [
-   ["@babel/plugin-syntax-typescript", { "isTSX": true }]
+   "@babel/plugin-syntax-typescript",
+   "@babel/plugin-syntax-jsx"
  ]
}
```
如果你正在使用 isTSX: false，你可以放心地把它移除。

`@babel/preset-flow`

note

也别忘了检查一下 @babel/plugin-transform-flow-strip-types 的更改，因为这个预设就是在底层使用它的。

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

迁移：该预设还会报告无效的选项名称。请参考文档并确保正确使用。
移除 allowDeclareFields 和 enums 选项 (#12457, #16792)

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

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

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

迁移：如果你不希望字段被初始化为 undefined，可以使用在 Flow 0.120 中引入的新 declare 语法：
input.js
```
class A {
  foo: string | void; // initialized to undefined
  declare bar: number; // type-only, will be removed
}
```

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

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

`@babel/plugin-transform-runtime`

corejs 选项已被移除 (#16311)

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

useESModules 选项已被移除 (#16141)

迁移：从你的配置中删除它。@babel/runtime 现在会在需要时自动暴露 ES 模块，使用 package.json#exports。
runtime 和 helpers 选项已被移除 (#16311)

迁移：从你的配置中删除它们：@babel/runtime 现在将始终导入 helpers。如果你不想向 helpers 注入导入项，请从配置中移除 @babel/plugin-transform-runtime。

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

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

迁移：在你的配置中添加 @babel/plugin-transform-dynamic-import：你在 Babel 7 中已经可以这样做了。如果你正在使用 @babel/preset-env，你无需做任何操作。
babel.config.js.diff
```
{
  "plugins": [
+   "@babel/plugin-transform-dynamic-import",
    "@babel/plugin-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)

Babel 7 以前会用 Babel 的 regeneratorRuntime 助手替换对 regeneratorRuntime 全局的引用：
input.js
```
console.log(regeneratorRuntime.isGeneratorFunction(fn));
```
output.js
```
import _regeneratorRuntime from "@babel/runtime/regenerator";
console.log(_regeneratorRuntime.isGeneratorFunction(fn));
```
在 Babel 8 中，这种情况不会再发生。

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

`@babel/plugin-proposal-decorators`

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

迁移：你应该迁移到提案的最新版本，"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" 选项。

虽然 Babel 8 仍然支持 legacy 版本，但无论如何建议迁移到 2023-11 版本：Babel 8 和 TypeScript 5.0 都支持 2023-11 版本，而在 legacy 版本中，Babel 和 tsc 的实现之间存在一些行为差异。浏览器只会实现该提案的最新版本。
移除 decoratorsBeforeExport: boolean 和 legacy: boolean 选项 (#17643)

迁移：这个改变是源自 version 候选项变更的优化：这些选项以前是旧版本装饰器所必需的，但现在你可以放心地从 Babel 配置中移除它们。

`@babel/plugin-proposal-pipeline-operator`

仅支持 fsharp 和 hack 提案 (#17732)

迁移：如果你使用过 smart 或 minimal 提案，你应该迁移到 fsharp 或 hack 提案上。

babel.config.json
{
  "plugins": [
    ["@babel/plugin-proposal-pipeline-operator", {
-     "proposal": "smart",
+     "proposal": "hack",
+     "topicToken": "%"
    }]
  ]
}

`@babel/eslint-plugin`

不再支持 ESLint 7 和 ESLint 8 (#17766)

迁移：将你的 ESLint 升级到 9 版本或以上。

`@babel/eslint-parser`

不再支持 ESLint 7 和 ESLint 8 (#17763)

迁移：将你的 ESLint 升级到 9 版本或以上。

移除 allowImportExportEverywhere 选项 (#13921)

迁移：改用 babelOptions.parserOpts.allowImportExportEverywhere。

.eslintrc
{
  "parser": "@babel/eslint-parser",
  "parserOptions": {
-   "allowImportExportEverywhere": true,
+   "babelOptions": {
+     "parserOpts": {
+       "allowImportExportEverywhere": true
+     }
+   }
  }
}

移除 @babel/eslint-parser/experimental-worker 入口点 (#17755)

迁移：基于工作线程的实现现在是唯一可用的：你现在可以从主 @babel/eslint-parser 入口访问它。
.eslintrc
```
{
-  "parser": "@babel/eslint-parser/experimental-worker",
+  "parser": "@babel/eslint-parser",
}
```
parserOpts.allowSuperOutsideMethod 默认是 false (#13921)

迁移：如果你想恢复到 Babel 7 的行为，将 babelOptions.parserOpts.allowSuperOutsideMethod 设置为 true。
parserOpts.allowSuperOutsideMethod 只接受顶层的 super (#17505)

迁移：避免无效的 super 使用。allowSuperOutsideMethod 的目的是在 Babel 模板中构建 super 节点，例如 template.ast`super()`, where only top-level super 是允许的。
allowReturnOutsideFunction 是从 ecmaFeatures.globalReturn 推断出来的 (#13921)

迁移：如果你想启用 allowReturnOutsideFunction，将 ecmaFeatures.globalReturn 设置为 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 起已被弃用。
Node.js 和 Babel 的命令行标志现在必须在文件名之前传递，而脚本本身的标志必须在文件名之后传递。(#16706)：
```
babel-node --flag-for-node --flag-for-babel script.js --flag-for-script
```

`@babel/standalone`

使用 browserslist 的 defaults 作为默认编译目标 (#12989, #15551)。

如果你已经在使用 data-targets 属性，这个改动对你不会有影响。

迁移：你可能对新行为没啥问题，因为 browserslist 的 defaults 覆盖了大多数现代浏览器。如果你需要支持旧版浏览器，指定 data-targets 属性即可。

移除默认启用语法的语法插件 (#17963)

以下插件，本来只用于启用各自 JavaScript 特性的解析支持，现在默认已经启用，因此不会在 @babel/standalone 中显示：
- @babel/syntax-async-generators
- @babel/syntax-class-properties
- @babel/syntax-class-static-block
- @babel/syntax-import-meta
- @babel/syntax-object-rest-spread
- @babel/syntax-optional-catch-binding
- @babel/syntax-top-level-await
迁移：从你的 @babel/standalone 配置中移除它们。

准备中​

Babel​

Node.js 支持​

仅限 ESM​

同伴依赖要求​

loose 和 spec 选项的弃用​

已重命名的软件包​

已停产的封装​

@babel/runtime-corejs2​

@babel/plugin-syntax-import-assertions​

@babel/plugin-proposal-import-attributes-to-assertions​

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

@babel/plugin-transform-object-assign​

@babel/plugin-transform-object-set-prototype-of-to-assign​

@babel/plugin-transform-react-compat​

@babel/plugin-transform-react-{source,self}​

@babel/plugin-transform-property-mutators​

语法插件​

每个软件包的重大变更​

@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/plugin-proposal-pipeline-operator​

@babel/eslint-plugin​

@babel/eslint-parser​

@babel/node​

@babel/standalone​

准备中

Babel

Node.js 支持

仅限 ESM

同伴依赖要求

`loose` 和 `spec` 选项的弃用

已重命名的软件包

已停产的封装

`@babel/runtime-corejs2`

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

`@babel/plugin-proposal-import-attributes-to-assertions`

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

`@babel/plugin-transform-object-assign`

`@babel/plugin-transform-object-set-prototype-of-to-assign`

`@babel/plugin-transform-react-compat`

`@babel/plugin-transform-react-{source,self}`

`@babel/plugin-transform-property-mutators`

语法插件

每个软件包的重大变更

`@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/plugin-proposal-pipeline-operator`

`@babel/eslint-plugin`

`@babel/eslint-parser`

`@babel/node`

`@babel/standalone`