Vite 插件 @vitejs/plugin-legacy 深度解析：旧浏览器兼容指南

📖 简介

@vitejs/plugin-legacy 是 Vite 官方提供的兼容性插件，专门用于为现代浏览器构建的应用程序提供对旧版浏览器的支持。该插件通过自动生成兼容性代码和 polyfill，确保您的应用能够在 IE 11 等旧版浏览器中正常运行。

核心价值

向后兼容: 让现代 Web 应用支持旧版浏览器
自动优化: 智能识别需要兼容的代码并自动处理
性能平衡: 在兼容性和性能之间找到最佳平衡点
零配置: 开箱即用，最小化配置复杂度

✨ 主要特性

1. 自动 Polyfill 注入

自动检测目标浏览器所需的 polyfill
智能按需加载，避免不必要的代码体积增加
支持 core-js 和 regenerator-runtime

2. 双重构建策略

现代版本: 使用现代 JavaScript 特性，体积更小，性能更好
兼容版本: 包含所有必要的 polyfill 和转换代码

3. 智能浏览器检测

基于 @babel/preset-env 的浏览器目标配置
支持自定义浏览器支持范围
自动生成 .browserslistrc 配置

4. 条件加载

现代浏览器加载现代版本代码
旧版浏览器自动降级到兼容版本
无缝的用户体验切换

🚀 安装与配置

安装依赖

复制代码

npm install @vitejs/plugin-legacy --save-dev

基础配置

复制代码

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

export default defineConfig({
  plugins: [
    legacy({
      targets: ["defaults", "not IE 11"],
    }),
  ],
});

完整配置示例

复制代码

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

export default defineConfig({
  plugins: [
    legacy({
      // 目标浏览器配置
      targets: ["ie >= 11"],

      // 额外的 polyfill
      additionalLegacyPolyfills: ["regenerator-runtime/runtime"],

      // 渲染 polyfill
      renderLegacyChunks: true,

      // 现代浏览器支持
      modernTargets: ["defaults", "not IE 11"],

      // 外部 polyfill
      external: ["core-js"],

      // 忽略特定文件
      ignoreBrowserslistConfig: false,

      // 核心 polyfill 配置
      corejs: {
        version: 3,
        proposals: true,
      },
    }),
  ],
});

🔧 配置选项详解

targets

指定需要支持的浏览器版本，支持以下格式：

复制代码

// 字符串数组
targets: ['ie >= 11', 'chrome >= 60']

// 对象格式
targets: {
  ie: '11',
  chrome: '60',
  firefox: '55'
}

// 使用 browserslist 查询
targets: ['> 1%', 'last 2 versions', 'not dead']

additionalLegacyPolyfills

添加额外的 polyfill 包：

复制代码

additionalLegacyPolyfills: [
  "regenerator-runtime/runtime",
  "core-js/features/promise",
  "core-js/features/array/find",
];

corejs

配置 core-js 的版本和特性：

复制代码

corejs: {
  version: 3,           // 使用 core-js 3.x
  proposals: true,      // 包含提案阶段的特性
  useBuiltIns: 'usage'  // 按需引入 polyfill
}

📱 使用示例

1. Vue 3 项目配置

复制代码

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import legacy from "@vitejs/plugin-legacy";

export default defineConfig({
  plugins: [
    vue(),
    legacy({
      targets: ["ie >= 11"],
      additionalLegacyPolyfills: ["regenerator-runtime/runtime"],
    }),
  ],
  build: {
    target: "es2015",
    minify: "terser",
  },
});

2. React 项目配置

复制代码

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import legacy from "@vitejs/plugin-legacy";

export default defineConfig({
  plugins: [
    react(),
    legacy({
      targets: ["defaults", "not IE 11"],
      modernTargets: ["chrome >= 87", "firefox >= 78"],
    }),
  ],
});

3. 企业级项目配置

复制代码

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

export default defineConfig({
  plugins: [
    legacy({
      targets: ["ie >= 11", "chrome >= 60", "firefox >= 55"],
      additionalLegacyPolyfills: [
        "regenerator-runtime/runtime",
        "core-js/features/promise",
        "core-js/features/array/find",
        "core-js/features/object/assign",
      ],
      corejs: {
        version: 3,
        proposals: true,
      },
      renderLegacyChunks: true,
      external: ["core-js"],
    }),
  ],
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          polyfills: ["core-js", "regenerator-runtime"],
        },
      },
    },
  },
});

🎯 最佳实践

1. 目标浏览器选择

复制代码

// 推荐配置
targets: ["ie >= 11", "chrome >= 60", "firefox >= 55"];

// 避免过度兼容
// ❌ 不推荐
targets: ["ie >= 9"]; // IE 9 支持成本过高

// ✅ 推荐
targets: ["ie >= 11"]; // IE 11 是合理的下限

2. Polyfill 优化

复制代码

// 按需引入 polyfill
corejs: {
  version: 3,
  proposals: false, // 生产环境关闭提案特性
  useBuiltIns: 'usage'
}

// 外部化常用 polyfill
external: ['core-js', 'regenerator-runtime']

3. 构建优化

复制代码

build: {
  // 分离 polyfill 到独立 chunk
  rollupOptions: {
    output: {
      manualChunks: {
        polyfills: ["core-js", "regenerator-runtime"];
      }
    }
  }
}

⚠️ 注意事项

1. 兼容性限制

不支持 IE 10 及以下版本
某些现代 Web API 无法完全 polyfill
CSS 特性兼容性需要额外处理

2. 性能考虑

旧版浏览器性能下降明显
建议设置合理的浏览器支持下限
监控实际用户浏览器分布

3. 维护成本

需要定期更新 polyfill 版本
测试覆盖多个浏览器版本
关注浏览器市场份额变化

🔮 未来发展趋势

基于用户实际访问数据
动态调整兼容性策略
智能 polyfill 选择

总结

@vitejs/plugin-legacy 是一个功能强大且易用的兼容性解决方案，它通过智能的构建策略和自动化的 polyfill 管理，让现代 Web 应用能够无缝支持旧版浏览器。合理使用该插件可以在兼容性和性能之间找到最佳平衡点，为您的项目提供更广泛的用户覆盖。

在选择使用该插件时，建议根据实际用户群体和业务需求来确定目标浏览器范围，避免过度兼容导致的性能损失和维护成本增加。

Vite 插件 @vitejs/plugin-legacy 深度解析：旧浏览器兼容指南 - 高质量源码分享平台-免费下载各类网站源码与模板及前沿技术分享