npm package: @qiaoge/vite-plugin-elnglegacy
Description: Vite 一站式兼容插件（JS+CSS 自动兼容旧浏览器，支持 Chrome ≥80+, 也可以自定义配置适配目标）
Author: elng
Latest version: 1.2.0

# @qiaoge/vite-plugin-elnglegacy

**Vite 一站式旧浏览器兼容解决方案 (JS + CSS)**

[![npm version](https://img.shields.io/npm/v/@qiaoge/vite-plugin-elnglegacy.svg)](https://www.npmjs.com/package/@qiaoge/vite-plugin-elnglegacy)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> 🚀 **核心理念**：让开发者不再为复杂的 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：

```bash
pnpm add -D @qiaoge/vite-plugin-elnglegacy
```

或者 npm / yarn：

```bash
npm install -D @qiaoge/vite-plugin-elnglegacy
# yarn add -D @qiaoge/vite-plugin-elnglegacy
```

## 🚀 快速开始

在 `vite.config.ts` 中引入并使用：

```typescript
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 类型提示。

### 基础配置

```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 变量转换等）是**自动开启**的。

```typescript
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，你也可以根据需要扩展。

```typescript
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` 选项：

```typescript
elngLegacyPlugin({
  legacy: {
    isMobile: true
  }
})
```
这会自动将兼容目标设置为 `ios >= 12` 等移动端常用基准。

---

## 📄 License

MIT

Copyright (c) 2024-present, elng & qiaoge