vitejs/plugin-legacy 作用与使用方法

文章目录

- - 一、核心作用
  - 二、快速使用步骤
  - - [1. 安装依赖](#1. 安装依赖)
    - [2. 配置 vite.config.js](#2. 配置 vite.config.js)
    - [3. 常用配置项说明](#3. 常用配置项说明)
    - [4. 构建与效果](#4. 构建与效果)
  - 三、常见场景示例
  - - [兼容 IE11](#兼容 IE11)
    - [只兼容现代浏览器（排除 IE）](#只兼容现代浏览器（排除 IE）)
    - [自定义 Polyfill](#自定义 Polyfill)
  - 四、注意事项

@vitejs/plugin-legacy 是 Vite 官方提供的旧版浏览器兼容插件，核心作用是让你用现代 ES 语法开发，同时自动生成兼容 IE11、旧版 Chrome/Safari 等不支持原生 ESM 的浏览器的代码包。

一、核心作用

Vite 默认只支持原生 ESM、动态 import、import.meta 的现代浏览器。启用该插件后，生产构建时会自动：

双包构建 ：为每个 chunk 生成两套代码
- 现代包：原生 ESM，给新浏览器用（<script type="module">）
- 旧版包：用 @babel/preset-env 转译 + SystemJS 模块，给老浏览器用
自动 Polyfill ：根据目标浏览器和代码实际使用，自动注入 core-js、regenerator-runtime、SystemJS 运行时
条件加载 ：在 HTML 注入 <script nomodule>，老浏览器只加载旧版包 + polyfill，新浏览器只加载现代包
环境变量 ：注入 import.meta.env.LEGACY，旧版包中为 true，可做分支逻辑

二、快速使用步骤

1. 安装依赖

bash 复制代码

# 安装插件与必要依赖
npm add -D @vitejs/plugin-legacy terser
# 或 yarn/pnpm
yarn add -D @vitejs/plugin-legacy terser
pnpm add -D @vitejs/plugin-legacy terser

必须装 terser，插件依赖它做代码压缩

2. 配置 vite.config.js

js 复制代码

import { defineConfig } from 'vite'
import legacy from '@vitejs/plugin-legacy'

export default defineConfig({
  plugins: [
    legacy({
      // 目标浏览器（browserslist 格式）
      targets: ['defaults', 'not IE 11'],
      // 额外 polyfill（可选）
      additionalLegacyPolyfills: ['regenerator-runtime/runtime'],
      // 是否生成 SystemJS 运行时（默认 true）
      renderLegacyChunks: true,
      // 现代包是否也做 polyfill（默认 false）
      modernPolyfills: false,
    }),
  ],
})

3. 常用配置项说明

配置项	类型	默认值	说明
`targets`	`string[]`	`['defaults']`	兼容目标，browserslist 语法
`additionalLegacyPolyfills`	`string[]`	`[]`	额外注入的 polyfill
`modernPolyfills`	`boolean`	`false`	现代包是否也加 polyfill
`renderLegacyChunks`	`boolean`	`true`	是否生成旧版包
`polyfills`	`boolean/string[]`	`true`	自定义 polyfill 列表

4. 构建与效果

执行 vite build，产物会包含：

现代包：index-xxx.js（<script type="module">）
旧版包：index-legacy-xxx.js（<script nomodule>）
Polyfill 包：polyfills-legacy-xxx.js

HTML 中自动插入：

html 复制代码

<!-- 现代浏览器 -->
<script type="module" src="/assets/index-xxx.js"></script>
<!-- 旧版浏览器 -->
<script nomodule src="/assets/polyfills-legacy-xxx.js"></script>
<script nomodule src="/assets/index-legacy-xxx.js"></script>

三、常见场景示例

兼容 IE11

js 复制代码

legacy({
  targets: ['ie >= 11', 'last 2 versions', '> 1%'],
  additionalLegacyPolyfills: ['regenerator-runtime/runtime'],
})

只兼容现代浏览器（排除 IE）

js 复制代码

legacy({
  targets: ['defaults', 'not IE 11', 'not IE < 11'],
})

自定义 Polyfill

js 复制代码

legacy({
  targets: ['chrome 58', 'ios 11'],
  // 只加指定 polyfill
  polyfills: ['es.promise.finally', 'es.array.flat'],
})

四、注意事项

只在生产构建生效 ：开发模式（vite dev）不生成旧版包
体积增加：旧版包 + polyfill 会增大产物，按需开启
动态 import：旧版包用 SystemJS 实现代码分割，现代包用原生 ESM
环境变量 ：import.meta.env.LEGACY 仅在旧版包中为 true，可用于分支逻辑