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 应用能够无缝支持旧版浏览器。合理使用该插件可以在兼容性和性能之间找到最佳平衡点，为您的项目提供更广泛的用户覆盖。

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