Svelte 浏览器支持矩阵：最低版本表、功能例外与自动化推导流水线

本文以 Svelte 仓库中机器生成的浏览器支持文档为核心，完整解读官方最低浏览器版本表（Baseline 2020 含义、各浏览器下限值）以及 $state.snapshot、bind:devicePixelContentBoxSize、flip 三类需要更高浏览器版本的功能例外，并结合 generate-browser-support.ts 与 browser-support.detector.js 源码，讲清这张表格是如何通过「rollup 打包 + TypeScript 类型感知扫描 + web-features 数据」全自动推导出来的。读完后，你可以准确判断自己的浏览器目标是否满足 Svelte 运行要求，并理解该文档每次更新背后的工程机制。

一、官方最低浏览器版本表

Svelte 仓库中，浏览器支持信息的正式载体是 browser-support.md 这份机器生成文档（文件首行注明 generated in packages/svelte/scripts/generate-browser-support.ts. do not edit），它被 Browser support 文档页 通过 @include 引入。官方表述为：该表列出的是「Svelte 内部代码所使用的浏览器 API」推导出的最低版本。当前生成的表格内容如下：

Browser	Minimum version
Chrome/Edge	87
Firefox	83
Safari	14
Opera	73
Opera (Android)	62
Samsung Internet	14.0
Android WebView	87
Internet Explorer	not supported

表格附有一条关键注释：该下限等价于 Baseline 目标为 2020。也就是说，Svelte 运行时整体满足 Web 平台「Baseline 2020」口径——即所有在该时间点达到 Baseline 的 Web 特性都能在表中列出的浏览器版本上运行。

官方文档页对范围有明确限定，这一点必须理解到位：

• 表格只覆盖 Svelte 本身（svelte 包的浏览器端运行时与其编译器输出代码）；
• 不包含 SvelteKit、其他 Svelte 生态库，也不包含你自己的业务代码——这些需要各自独立评估；
• 表格由脚本生成，因此版本下限不是人工拍定的承诺，而是对当前代码实际用到的浏览器 API 的客观测量结果。

二、功能例外：需要高于运行时下限的浏览器

「只覆盖 Svelte 本身」并不意味着所有 Svelte 功能都能在 Chrome 87 / Firefox 83 / Safari 14 上工作。官方文档页设有 Exceptions 小节，引入第二份机器生成表 browser-support-features.md。其含义是：只有当你的代码用到了下列特定功能时，才需要考虑更高的浏览器版本。当前生成的例外表（列仅含 Chrome/Edge、Firefox、Safari 三大核心浏览器，— 表示该浏览器已达到运行时下限、无需额外关注）：

Feature	Chrome/Edge	Firefox	Safari
$state.snapshot	98	94	15.4
bind:devicePixelContentBoxSize	—	93	not supported
flip from svelte/animate	—	126	—

每一行例外都能在当前仓库源码中找到直接依据：

1. $state.snapshot —— 依赖 structuredClone

$state.snapshot 用于对状态做不可变快照，其底层实现位于 clone.js，在快照路径上直接调用全局 structuredClone(value)（约 L110、L131）。structuredClone 在三大浏览器中的可用版本分别为 Chrome 98、Firefox 94、Safari 15.4，恰好与例外表一致。因此：在 Chrome 87–97、Firefox 83–93 或 Safari 14 上，Svelte 其余功能正常，唯独 $state.snapshot 不可用。

2. bind:devicePixelContentBoxSize —— 依赖 ResizeObserver 的 device-pixel-content-box 选项

该绑定的运行时实现在 size.js（L74 附近以 box: 'device-pixel-content-box' 构造 ResizeObserver）。生成脚本的注释（generate-browser-support.ts L84-L91）说明了 Safari 的特殊性：Safari 自 15.4 起静默接受构造选项，但从未暴露 ResizeObserverEntry.devicePixelContentBoxSize 属性，因此在任何 Safari 版本上该绑定读到的都是 undefined，故表中记为 not supported；Firefox 则需 93 及以上。

3. flip（svelte/animate）—— Firefox 需要 126

flip 动画的补偿计算在 animate/index.js L73 处执行 zoom *= +getComputedStyle(current).zoom;。Firefox 直到 v126（2024 年 5 月）才在 CSSStyleDeclaration 上暴露 .zoom，此前的版本该读取返回空字符串，破坏动画数学。由于 web-features 数据集没有该 API 的条目，生成脚本通过补充检测规则（register_extra_rules，L73-L79）手工登记了 CSS zoom property reads 规则并指定 versions: { firefox: '126' }。

三、表格是如何自动推导的：四步流水线

browser-support.md 顶部注释指向生成器 generate-browser-support.ts。该脚本头部注释完整描述了流水线，结合 main()（L806-L860）可归纳为四步：

第 1 步：按「用户实际收到的代码」打包全部浏览器端入口

脚本从 svelte 包的 exports 映射中枚举所有面向浏览器的子路径（browser_subpaths() L161-L171），显式排除仅 Node 端的 ./compiler、./server、./internal/server。对每个入口（svelte、svelte/animate、svelte/transition、svelte/store 等），用 rollup 以 production/import/browser/default 导出条件打包（bundle() L292-L329），并将 esm-env 等 Node 专用分支置为 external——保证扫描的是浏览器真正会执行的代码，且已树摇。

第 2 步：TypeScript 类型感知扫描，识别用到的 Web 特性

打包产物写入临时目录后交给 browser-support.detector.js。检测器基于 web-features 数据集构建三类查找表（build_detection_maps() L67-L146）：

• 全局标识符：api.X（如 ResizeObserver）与 javascript.builtins.X（如 Promise、Proxy）映射到全局名；
• 成员访问：api.X.Y（如 HTMLElement.inert）与 javascript.builtins.X.Y（静态方法额外登记 XConstructor 形式）映射到「接收者类型 → 成员 → feature_id」，运行时用 TypeChecker 解析 expr.member 中 expr 的实际类型，并沿基类链匹配（get_type_names() L246-L263，因此 HTMLDivElement 能命中 HTMLElement 的规则）；
• JS 语法谓词：SYNTAX_PREDICATES（L12-L61）覆盖空值合并、逻辑赋值、可选链、展开、解构、箭头函数、for await、私有类字段、异步/普通生成器、async 函数、class、let/const、模板字面量等，这些不依赖类型信息。

此外还有字符串字面量规则（按值匹配，用于像 'device-pixel-content-box' 这类过于独特、不会偶然出现的 API 选项字符串）和 register_extra_rules()（L188-L211）供登记 web-features 尚未收录的 API（如前述 CSS zoom 读取）。

编译器输出代码同样纳入扫描：脚本读取 snapshot 测试 下每个样本 _expected/client 目录中的编译产物（load_compiler_output_fixtures() L336-L353），以纯语法模式扫描，覆盖编译器会 emit 的全部模式——绑定、转场、<svelte:element>、async derived、hydration 标记等。

第 3 步：计算运行时下限与逐功能条件表

• 运行时下限：compute_floor()（L395-L412）取所有被检测到特性的 Baseline 年份最大值作为「地板」，并以 Math.max(year, 2015) 保底（L437-L439），确保文档永远不会声称目标是 ES6 之前；随后用 baseline-browser-mapping 的 getCompatibleVersions({ targetYear, includeDownstreamBrowsers: true })（browser_versions_for() L702-L751）把年份翻译成具体浏览器版本。输出表中省略了与桌面版版本相同的 Android/iOS 变体行，只保留值得列出的下游浏览器集合（chrome、edge、firefox、safari、opera、samsunginternet_android、webview_android 等），Internet Explorer 恒为 not supported（L785）。
• 逐功能条件表：enumerate_features()（L484-L523）为每一类用户可见功能构造自包含测试夹具——编译器 binding_properties 中的每个 bind:*（按 valid_elements 生成合法标记，如 checked/indeterminate 配 type="checkbox"）、每个公开子包的每个具名导出（动态 import 枚举，L195-L212）、编译器 RUNES 数组中的每个 rune（$state 到 $host，含 $state.raw、$effect.tracking 等）、以及需要配套 import 的指令（transition:/in:/out:、animate:、use:、{@attach}、{@html}、custom elements）。每个夹具经 svelte_compile 编译 → rollup 打包 → 类型感知扫描；若夹具地板高于运行时地板，render_conditional_table()（L669-L700）就为它输出一行，版本优先取 web-features 的精确 per-browser 数据（versions_from_features() L365-L388，取各特性最严版本、null 表示 not supported 并向上传播），无精确数据才回退年份映射。

第 4 步：防「注释腐化」的自愈校验

脚本区分两类抑制集：

• SAFE_TO_IGNORE（L131：devicepixelratio、trusted-types）：无论运行时是否使用都永远不影响下限。原因有二——web-features 数据集误分类（如 devicepixelratio 因 Safari 支持映射缺失被标 Baseline false，但该属性在 Safari 已存在十余年）；或 Svelte 在运行时做了特性探测并优雅降级，典型例子是 reconciler.js 中对 globalThis.window.trustedTypes 的可选链调用创建 svelte-trusted-html 策略。
• BEHAVIORAL_IGNORE（L138-L142：structured-clone、extra:css-zoom-read、extra:device-pixel-content-box）：这些 API 确实存在于运行时、但仅经由特定功能路径触达，因此其成本记入上文的逐功能例外表而非整体下限。validate_ignore_features()（L458-L472）会校验每个条目仍被检测器实际标记——如果运行时已移除某 API，该条目会直接抛出错误要求删除，防止「行为抑制项比它所抑制的 API 活得还久」。

四、对使用者的实践含义

1. 判断兼容性：如果你的项目浏览器目标不低于「Chrome/Edge 87、Firefox 83、Safari 14、Opera 73、Samsung Internet 14.0、Android WebView 87」且不使用第二节列出的三个例外功能，Svelte 运行时本身不构成兼容性问题。
2. 例外功能的取舍：使用 $state.snapshot、bind:devicePixelContentBoxSize 或 animate:flip 时需分别核对 Chrome 98 / Firefox 94 / Safari 15.4、Firefox 93（Safari 不可用）、Firefox 126 这几个更高的门槛；若目标浏览器不满足，应准备降级方案（如不快照、改用 contentBoxSize、换用 svelte/transition 中的其他动画）。
3. 不要把该表当作项目总预算：表格只测量 Svelte 自身代码，SvelteKit、第三方库与业务代码各自独立计入兼容性评估。
4. 不要手工编辑生成文档：.generated/browser-support.md 与 browser-support-features.md 均由 generate-browser-support.ts 重写；当 Svelte 运行时新增或移除某个浏览器 API 时，重新运行脚本即可让表格自动收敛——BEHAVIORAL_IGNORE 的陈旧条目检查（第 3 节第 4 步）正是这一自愈机制的组成部分。