如何使用 Vite 进行语法降级和 Polyfill

可能很多人都觉得 Vite 是一个现代前端构建工具，应该在现代浏览器中使用，放到各种语法特性都缺失的低版本浏览器(如 ie 11)就不适用了。这种观念对不对呢？是不对的。 通过 Vite 构建我们完全可以兼容各种低版本浏览器，打包出既支持现代（Modern）浏览器又支持旧版（Legacy）浏览器的产物。

以下是在线上环境的一些报错 某些低版本浏览器并没有提供 Promise 语法环境以及对象和数组的各种 API，甚至不支持箭头函数语法，代码直接报错，从而导致线上白屏事故的发生，尤其是需要兼容到IE 11、iOS 9 以及 Android 4.4 的场景中很容易会遇到。

旧版浏览器的语法兼容问题主要分两类：

这两类问题本质上是通过前端的编译工具链（如 Babel）以及 JS 的基础 Polyfill 库（如 corejs）来解决的，不会跟具体的构建工具所绑定。 也就是说，对于这些本质的解决方案，在其它的构建工具（如 Webpack）能使用，在 Vite 中也完全可以使用。

构建工具考虑的仅仅是如何将这些底层基础设施接入到构建过程的问题，自己并不需要提供底层的解决方案，正所谓术业有专攻，把专业的事情交给专业的工具去做。

接下来的部分，我就来带你熟悉一下所谓专业的工具到底有哪些，以及如何使用这些工具。

解决上述提到的两类语法兼容问题，主要需要用到两方面的工具，分别包括:

编译时工具的作用是在代码编译阶段进行语法降级以及**添加 polyfill 代码的引用语句，**例如：

由于这些工具只是编译阶段用到，运行时并不需要，我们需要将其放入 devDependencies 中

而运行时基础库是根据 ESMAScript 官方语言规范提供各种 Polyfill 实现代码。主要包括 core-js 和 regenerator-runtime 两个基础库。 不过在 babel 中也会有一些上层的封装，包括：

这些各种运行时库看似眼花缭乱，其实都是 core-js 和 regenerator-runtime 不同版本的封装罢了。（@babel/runtime 是个特例，不包含 core-js 的 Polyfill）这类库是项目运行时必须要使用到的，因此一定要放到 package.json 中的 dependencies 中！

首先安装一些必要的依赖：

解释一下各个依赖的作用：

接着新建 src 目录，在目录下增加 index.js 文件：

示例代码中既包含了高级语法也包含现代浏览器的 API，正好可以针对语法降级和 Polyfill 注入两个功能进行测试。

接下来新建 .babelrc.json 即 babel 的配置文件，内容如下：

其中有两个比较关键的配置：targets 和 usage

我们可以通过 targets 参数指定要兼容的浏览器版本，有两种配置方法。 对象配置：

用 Browserslist 配置语法：

Browserslist 是一个帮助我们设置目标浏览器的工具，不光是 Babel 用到，其他的编译工具如 postcss-preset-env、autoprefix 中都有所应用。 对于 Browserslist 的配置内容，你既可以放到 Babel 这种特定工具当中，也可以在 package.json 中通过 browserslist 声明：

或者通过 .browserslistrc 进行声明：

在实际的项目中，一般我们可以将使用下面这些最佳实践集合来描述不同的浏览器类型，减轻配置负担：

接下来我们来看另外一个重要的配置：useBuiltIns，它决定了添加 Polyfill 的策略，默认是 false，即不添加任何的 Polyfill。 你可以手动将 useBuiltIns 配置为 "entry" 或者 "usage"，接下来我们看看这两个配置究竟有什么区别。

首先你可以将这个字段配置为 entry，需要注意的是，entry 配置规定你必须在入口文件手动添加一行这样的代码：

接着在终端执行下面的命令进行 Babel 编译：

产物输出在 dist 目录中，你可以去观察一下产物的代码： Babel 已经根据目标浏览器的配置为我们添加了大量的 Polyfill 代码，index.js 文件简单的几行代码被编译成近 300 行。 实际上，Babel 所做的事情就是将你的 import "core-js" 代码替换成了产物中的这些具体模块的导入代码。

但这个配置有一个问题，即无法做到按需导入，上面的产物代码其实有大部分的 Polyfill 的代码我们并没有用到。 接下来我们试试 useBuiltIns: "usage" 这个按需导入的配置，改动配置后执行编译命令，查看产物输出：

Polyfill 代码主要来自 corejs 和 regenerator-runtime，因此如果要运行起来，必须要装这两个库。

可以发现 Polyfill 的代码精简了许多，真正地实现了按需 Polyfill 导入。 因此，在实际的使用当中，还是推荐大家尽量使用 useBuiltIns: "usage"，进行按需的 Polyfill 注入。

我们来总结一下，上面我们利用 @babel/preset-env 进行了目标浏览器语法的降级和 Polyfill 注入，同时用到了 core-js 和 regenerator-runtime 两个核心的运行时库。 但 @babel/preset-env 的方案也存在一定局限性：

接下来要介绍的 transform-runtime 方案，就是为了解决 @babel/preset-env 的种种局限性。

需要提前说明的是，transform-runtime 方案可以作为 @babel/preset-env 中 useBuiltIns 配置的替代品。 也就是说，一旦使用 transform-runtime 方案，你应该把 useBuiltIns 属性设为 false。

接下来我们来尝试一下这个方案，首先安装必要的依赖：

解释一下这两个依赖的作用：

core-js 有三种产物，分别是 core-js、core-js-pure 和 core-js-bundle 第一种是全局 Polyfill 的做法，@babel/preset-env 就是用的这种产物 第二种不会把 Polyfill 注入到全局环境，可以按需引入 第三种是打包好的版本，包含所有的 Polyfill，不太常用

@babel/runtime-corejs3 使用的是第二种产物

接着我们对 .babelrc.json 作如下的配置：

@babel/preset-env 是用到的基础 plugin 的预设，@babel/plugin-transform-runtime 是对 plugin 的扩展

对比一下最终产物结果： 经过对比我们不难发现：

另外，transform-runtime 方案引用的基础库也发生了变化，不再是直接引入 core-js 和 regenerator-runtime，而是引入 @babel/runtime-corejs3

好，介绍完了 Babel 语法降级与 Polyfill 注入的底层方案，接下来我们来看看如何在 Vite 中利用这些方案来解决低版本浏览器的兼容性问题。

Vite 官方已经为我们封装好了一个开箱即用的方案：@vitejs/plugin-legacy，我们可以基于它来解决项目语法的浏览器兼容问题。

这个插件内部同样使用 @babel/preset-env 以及 core-js 等一系列基础库来进行语法降级和 Polyfill 注入。

因此对于上文所介绍的底层工具链的掌握是必要的，否则无法理解插件内部所做的事情，真正遇到问题时往往会不知所措。

安装一下官方的插件：

随后在项目中使用它：

我们同样可以通过 targets 指定目标浏览器，这个参数在插件内部会透传给 @babel/preset-env

在引入插件后，我们可以尝试执行 npm run build 对项目进行打包，可以看到如下的产物信息： 相比一般的打包过程，多出了 index-legacy.js、vendor-legacy.js 以及 polyfills-legacy.js 三份产物文件。

让我们继续观察一下 index.html 的产物内容：

通过官方的 legacy 插件，Vite 会分别打包出 Modern 模式和 Legacy 模式的产物，然后将两种产物插入同一个 HTML 里面，Modern 产物被放到 type="module" 的 script 标签中，而 Legacy 产物则被放到带有 nomodule 的 script 标签中。 浏览器对于这两种 script 标签的加载策略如下图所示： 这样产物便就能够同时放到现代浏览器和不支持 type="module" 的低版本浏览器当中执行。

当然，在具体的代码语法层面，插件还需要考虑语法降级和 Polyfill 按需注入的问题，接下来我们就来分析一下 Vite 的官方 legacy 插件是如何解决这些问题的。

官方的 legacy 插件是一个相对复杂度比较高的插件，直接看源码可能会很难理解，这里我梳理了画了一张简化后的流程图，接下来我们就根据这张流程图来一一拆解这个插件在各个钩子阶段到底做了些什么。 首先是在 configResolved 钩子中调整了 output 属性，这么做的目的是让 Vite 底层使用的打包引擎 Rollup 能另外打包出一份 Legacy 模式的产物，实现代码如下：

接着，在 renderChunk 阶段，插件会对 Legacy 模式产物进行语法转译和 Polyfill 收集，值得注意的是，这里并不会真正注入 Polyfill，而仅仅只是收集 Polyfill：

由于场景是应用打包，所以这里直接使用 @babel/preset-env 的 useBuiltIns: 'usage' 来进行全局 Polyfill 的收集是比较标准的做法。

回到 Vite 构建的主流程中，接下来会进入 generateChunk 钩子阶段，现在 Vite 会对之前收集到的 Polyfill 进行统一的打包，实现也比较精妙，主要逻辑集中在 buildPolyfillChunk 函数中：

因此，你可以理解为这个函数的作用即通过 vite build 对 renderChunk 中收集到的 polyfill 代码进行打包，生成一个单独的 chunk：

需要注意的是，polyfill chunk 中除了包含一些 core-js 和 regenerator-runtime 的相关代码，也包含了 SystemJS 的实现代码，你可以将其理解为 ESM 的加载器，实现了在旧版浏览器下的模块加载能力。

现在我们已经能够拿到 Legacy 模式的产物文件名及 Polyfill Chunk 的文件名，那么就可以通过 transformIndexHtml 钩子来将这些产物插入到 HTML 的结构中：

Vite 官方的 legacy 插件的主要原理就介绍到这里，为了方便大家理解，讲解的过程中忽略了一些与主流程关联不大的细节，最后给大家补充一下：