@qiaoge/vite-plugin-elnglegacy

Vite 一站式旧浏览器兼容解决方案 (JS + CSS)

🚀 核心理念：让开发者不再为复杂的 Babel、PostCSS、Browserslist 配置头疼，只需引入一个插件，即可获得“专业级”的旧浏览器兼容性支持。

❓ 为什么你需要这个插件？

在使用 Vite 开发时，兼容旧浏览器（如 Chrome < 80, iOS < 13）通常是一场配置噩梦。你是否遇到过以下痛点：

❌ 常见痛点

1. 兼容性配置割裂：
   • 为了 JS 兼容，你配置了 @vitejs/plugin-legacy。
   • 为了 CSS 前缀（如 -webkit-），你又要去配 autoprefixer。
   • 为了 CSS 新特性（如嵌套、变量），你还得配 postcss-preset-env。
   • 一旦忘记同步各处的 targets（目标浏览器），就会出现 JS 能跑但样式错乱的尴尬。
2. 白屏地狱：
   • 项目在旧手机上白屏，控制台报错 Array.prototype.at is not a function 或 FormData is not defined。
   • 你只能手动一个个查文档，然后把缺失的 Polyfill 加回去。
3. 配置繁琐：
   • 要手动管理 core-js 版本，要区分移动端和 PC 端的兼容策略。

✅ 解决方案

@qiaoge/vite-plugin-elnglegacy 完美解决了上述所有问题：

• ✨ JS + CSS 全栈兼容：一个插件同时接管 JS 降级（基于 @vitejs/plugin-legacy）和 CSS 处理（自动注入 autoprefixer 和 postcss-preset-env）。
• 🎯 单一数据源：只需配置一次 targets，自动分发给 JS 和 CSS 编译器。
• 🔋 电池内置：内置了实战中总结的高频缺失 Polyfill 清单（如 at, flat, all-settled），开箱即用，拒绝白屏。
• 📱 移动端预设：一键开启移动端最佳实践配置，无需纠结 Android/iOS 版本细节。

📦 安装

推荐使用 pnpm：

pnpm add -D @qiaoge/vite-plugin-elnglegacy

或者 npm / yarn：

npm install -D @qiaoge/vite-plugin-elnglegacy
# yarn add -D @qiaoge/vite-plugin-elnglegacy

🚀 快速开始

在 vite.config.ts 中引入并使用：

import { defineConfig } from 'vite';
import elngLegacyPlugin from '@qiaoge/vite-plugin-elnglegacy';

export default defineConfig({
  plugins: [
    elngLegacyPlugin({
      // 目标浏览器配置 (可选，默认兼容 Chrome 80+)
      targets: [
        'chrome >= 64',
        'safari >= 12',
        'ios >= 12',
        'firefox >= 60',
        'edge >= 79'
      ]
    })
  ]
});

⚙️ 配置选项 (Options)

插件提供了丰富的配置项，且拥有完整的 TypeScript 类型提示。

基础配置

interface ElngLegacyOptions {
  /**
   * 目标浏览器范围 (Browserslist query)
   * @default ["chrome >= 80", "safari >= 13.1", "firefox >= 72", "edge >= 80"]
   */
  targets?: string | string[];

  /**
   * 开启移动端预设模式
   * 自动设置 targets 为主流旧版移动端浏览器 (iOS 12+, Android Chrome 64+)
   * @default false
   */
  legacy?: {
    isMobile?: boolean;
  };
}

CSS 兼容性配置

默认情况下，CSS 兼容性功能（自动前缀、CSS 变量转换等）是自动开启的。

interface CssOptions {
  /** 是否启用自动添加厂商前缀 (Autoprefixer) @default true */
  autoprefixer?: boolean;
  
  /** 是否转换 CSS 自定义属性 (CSS Variables) @default true */
  customProperties?: boolean;
  
  /** 是否转换 CSS 嵌套规则 @default true */
  nestingRules?: boolean;
  
  /** 是否转换 :is() 选择器 @default true */
  selectorIs?: boolean;
}

// 使用示例
elngLegacyPlugin({
  css: {
    autoprefixer: true,
    nestingRules: true
  }
})

Polyfill 高级配置

插件内置了最常用的 Polyfill，你也可以根据需要扩展。

interface ElngLegacyOptions {
  /**
   * 强制注入的 Polyfills
   * 默认包含: es.array.at, es.promise.all-settled, es.object.has-own 等
   */
  polyfills?: string[];

  /**
   * 额外追加的 Polyfills (在默认列表基础上增加)
   */
  extraPolyfills?: string[];

  /**
   * 是否注入 regenerator-runtime (用于 async/await)
   * @default true
   */
  regenerator?: boolean;

  /**
   * 是否注入 formdata-polyfill
   * @default true
   */
  enableFormDataPolyfill?: boolean;
}

🛠️ 常见问题

Q: 这个插件和 @vitejs/plugin-legacy 有什么区别？

A: @vitejs/plugin-legacy 仅负责 JS 语法的降级和 Polyfill 注入。本插件包含了它，并在此基础上增加了 CSS 自动兼容（PostCSS 配置）、智能 Polyfill 预设 和 统一的 Targets 管理。它是对原生插件的封装和增强。

Q: 我已经配置了 postcss.config.js，会冲突吗？

A: 不会。插件会智能合并您的自定义 PostCSS 配置。但建议将兼容性相关的配置（如 autoprefixer）交给本插件管理，您只需关注业务相关的 PostCSS 插件（如 TailwindCSS）。

Q: 移动端项目怎么配置最合适？

A: 建议开启 legacy.isMobile 选项：

elngLegacyPlugin({
  legacy: {
    isMobile: true
  }
})

这会自动将兼容目标设置为 ios >= 12 等移动端常用基准。

📄 License

MIT

Copyright (c) 2024-present, elng & qiaoge