Vite 浏览器兼容与 Legacy 构建：build.target、Polyfill 与兼容插件

- 开发模式：浏览器直接加载原生 ESM 模块
- 生产构建：build.target 默认 'modules'（≈ 基线 2020+）

- 原生 ESM（<script type="module">）
- 较新语法：可选链 ?. 、空值合并 ?? 、BigInt、逻辑赋值
- 不支持的：旧浏览器（无 ESM）、IE 全系、Safari < 10.1 等

- 内部系统/桌面工具：用户可控 → 现代目标即可
- 公网 ToC：存在旧设备 → 要 legacy 构建
- 老年/政务/教育场景：旧浏览器占比高 → legacy + polyfill 全套

// vite.config.js
export default {
  build: {
    target: "es2018",   // 或 'modules'（默认）/ 具体浏览器版本
  },
};

✓ 语法降级：可选链 → 三元、空值合并 → 逻辑表达式、async/await → ...
✓ 转换 class 字段、BigInt 字面量
✗ 不注入 polyfill：Promise.finally、Array.includes 等 API 缺失不管
✗ 不降级动态 import 到非 ESM 方案（除非 legacy 插件）

'build.target': 'es2018'         → ES 版本
'chrome87' / 'safari14' / 'edge88' → 具体浏览器
'esnext'                        → 完全不做语法降级

target 越新 → 产物越小（语法更紧凑）
target 越旧 → 兼容越广但产物越大（转译膨胀）
→ 别盲目 es5：对大多数项目，'modules' + legacy 双构建是最优解

现代构建：现代语法 + 原生 ESM → 新浏览器用（小、快）
遗留构建：降级语法 + 兼容加载 → 老浏览器用（大、稳）

<!-- 现代浏览器：type="module" 生效 -->
<script type="module" src="/assets/modern-index.js"></script>

<!-- 老浏览器：不认识 module 标签 → 跳过上面的，走这里 -->
<script nomodule src="/assets/legacy-index.js"></script>

- 现代浏览器用现代包 → 体积小、性能好
- 老浏览器用兼容包 → 能用就行
- 单 es5 方案 = 所有人吃最差性能（现代用户被拖累）

npm i -D @vitejs/plugin-legacy

// vite.config.js
import legacy from "@vitejs/plugin-legacy";

export default {
  plugins: [
    legacy({
      targets: ["ie >= 11", "chrome >= 49", "safari >= 10"],
      additionalLegacyPolyfills: ["regenerator-runtime/runtime"],
    }),
  ],
};

- 用 Babel/Terser 生成 legacy 版（语法降级到 targets 允许的范围）
- 按 targets 生成 polyfill 清单（基于 core-js）
- 产出两套资源 + HTML 里 module/nomodule 分流
- 老浏览器先加载 legacy polyfill（Promise 等），再跑 legacy 主包

- legacy 构建会让产物变大（两套）、构建变慢（Babel 二次转译）
- 若用户群全是现代浏览器 → 不装这个插件，最省
- Safari 动态 import 的坑：现代包也可能需要 polyfill（下节）

① 全量 core-js（大而全）
   import "core-js";        // 全部 polyfill → 体积大但稳
② 按需（babel/preset-env + useBuiltIns）
   只注入 targets 缺的 → 体积适中
③ Polyfill.io 服务（运行时按 UA 下发）
   <script src="https://polyfill.io/v3/polyfill.min.js?features=Promise,fetch">
   缺点：外部依赖、按 UA 缓存策略复杂

// 现代包：一般不带 polyfill（现代浏览器自带）
// legacy 包：plugin-legacy 按 targets 自动注入 core-js polyfill

// package.json
{
  "browserslist": [
    "defaults",
    "not ie <= 10",
    "> 0.2%",
    "not dead"
  ]
}

defaults          → 全球默认（>0.5%, 最新两版, 非 dead）
> 1% in CN        → 中国使用率 > 1%
not ie <= 10      → 排除 IE10 及以下
last 2 versions   → 最近两个大版本
covered 95% in CN → 覆盖中国 95% 用户

// plugin-legacy 直接读 browserslist 字段
legacy({ targets: "defaults" })
// 或显式数组
legacy({ targets: ["> 0.2%", "not dead", "not ie <= 10"] })

npx browserslist "> 0.2% in CN" --coverage   # 看覆盖度

- legacy 包把动态 import 转成 SystemJS 加载（插件内置）
- 现代包若也遇到动态 import 兼容问题 → 用 modernPolyfills 或 SystemJS 回退

<!-- legacy 分支：先加载 SystemJS，再加载 legacy 入口 -->
<script nomodule> System.import('./legacy-index.js') </script>

- 你的代码大量用 React.lazy / 动态 import → 老浏览器更依赖 SystemJS 兜底
- 只兼容"现代 + 稍旧"（如 Chrome 70+）→ 动态 import 基本没问题
- Safari 10.x 特殊：支持 ESM 但不支持动态 import → 常被坑

① caniuse.com 查 API 支持 → 规划 polyfill（静态）
② 浏览器模拟（Playwright/BrowserStack） → 自动化冒烟
③ 真实设备/降级网速 → 最终验收

// playwright.config.js
const devices = ["Desktop Chrome", "Safari 14", "Safari 11"];
// 或 BrowserStack/SauceLabs 的真机矩阵

- 首页能渲染（非白屏）
- 动态 import 的懒加载路由能进
- 表单/交互正常（polyfill 是否影响行为）
- 网络节流下（3G）首屏仍可用

# 本地验证 legacy 包
npx vite build && npx serve dist
# 用旧浏览器打开（或 Playwright 模拟），看是否走 nomodule
# DevTools → Application → 检查 <script nomodule> 是否执行

□ 用户浏览器分布？（GA/站点分析）
□ 目标覆盖：> 95% 的最小 browserslist 集合
□ 是否需要 legacy 双构建？（有 IE/旧 Safari/旧 Android 就装）
□ polyfill 策略：按需注入 or 外部服务？
□ 现代包是否要补新 API polyfill？（用了 replaceAll 等）
□ 动态 import 场景多不多？（决定 SystemJS 依赖程度）
□ 测试矩阵：模拟 + 真机 + 节流
□ 性能代价：legacy 会让产物变大、构建变慢——值不值？