Svelte 5 之前的全部版本演进:从 CHANGELOG-pre-5.md 读懂 411 次发布的完整脉络

Svelte 5 之前的全部版本演进:从 CHANGELOG-pre-5.md 读懂 411 次发布的完整脉络

【免费下载链接】svelteweb development for the rest of us项目地址: https://gitcode.com/GitHub_Trending/sv/svelte

Svelte 仓库将 5.0 之前的全部发布历史单独归档在 CHANGELOG-pre-5.md 中,该文件从 0.0.1 一直记录到 4.2.3,共包含 411 个版本条目,是理解 Svelte 从 2016 年初代编译器到 4.x 稳定期技术决策演进的完整一手资料。本文以这份归档 changelog 为主体,结合当前仓库源码(主包版本为 5.57.0),系统梳理各时代的标志性能力、4.0.0 的全部破坏性变更及其迁移路径,帮助你在维护遗留项目或排查老版本行为差异时,能快速定位功能是在哪个版本引入、哪些行为在升级时发生了改变。

一、文档定位:两个 changelog 文件的分界线

当前仓库中,版本记录被拆分为两个文件:

• packages/svelte/CHANGELOG-pre-5.md:5.0 之前的全部历史,覆盖 0.0.1 至 4.2.3,共 2926 行、411 个##版本小节;
• packages/svelte/CHANGELOG.md:5.0 及之后的版本,当前最新条目为 5.57.0。

这种拆分与 package.json 中"version": "5.57.0"的事实一致:Svelte 5 发布后,历史档案被移出主 changelog,以便主文件保持轻量、便于当前版本的维护者更新。因此,当你需要回答"某个语法特性是哪个版本加入的""3.x 与 4.x 之间绑定行为有何变化"这类问题时,答案都在 CHANGELOG-pre-5.md 中;而 5.x 的 runes 时代变更则在 CHANGELOG.md 中,且 5 的迁移说明另见 07-v5-migration-guide.md。

两种记录格式

文件中存在明显的格式断层,阅读时需要注意:

• 4.x 时代(文件开头部分):采用 changesets 风格的三段式结构,每个版本下分Major Changes/Minor Changes/Patch Changes小节,例如 4.0.0 小节;
• 3.x 及更早:每条直接以无序列表平铺,没有级别标注,条目密度高,例如 3.56.0 小节 单版本就有 30 余条修复。

每条条目几乎都附带原始 issue/PR 编号(如#8566),这是本文后续"如何检索"部分的基础。

二、时代划分:从 0.0.1 到 4.2.3 的里程碑地图

整份档案可以按大版本划分为五个时代,下表中每个里程碑均直接引自 changelog 原文条目:

几个值得注意的演进模式:

1. 模板语法只改了一次。2.0.0 的"New template syntax"是 Svelte 模板层的唯一一次大换血(双花括号 → 单花括号,同时onstate/onupdate钩子取代component.observe,computed 属性改为解构语法)。此后 3.x、4.x 的所有新特性({#key}、{@const}、<svelte:element>等)都是增量式添加。
2. a11y 警告是 3.x 的长期主线。从 3.22.0 的a11y-img-redundant-alt、3.39.0 的a11y-mouse-events-have-key-events,到 3.50.0/3.56.0 成批加入的 ARIA 角色检查,编译期无障碍检查规则几乎每个 minor 版本都在扩充,当前仓库的 a11y 警告定义 就是这条路线的延续。
3. 编译器 API 渐进公开。3.2.0 导出parse/walk,3.53.0 扩展css选项为'external' | 'injected' | 'none',3.39.0 加入errorMode——这些是后来 preprocessor 生态(如当前仓库 preprocess 实现)能繁荣的前提。

三、4.0.0 破坏性变更全解读(重点)

4.0.0 是这份档案中唯一以 "breaking" 显式标注大段条目的版本,它直接为 Svelte 5 的发布铺平了道路。changelog 原文将变更分为三档,下面逐条给出要点与影响面。

3.1 环境与服务端(Major Changes)

引自 4.0.0 Major Changes:

• 最低 Node 版本提升到Node 16;
• 最低 webpack 版本提升到webpack 5;
• 打包器构建浏览器端 bundle 时必须声明browser条件,否则onMount等生命周期回调不会执行(SvelteKit 与 Vite 会自动处理);Rollup 需在@rollup/plugin-node-resolve中设置browser: true,webpack 需将"browser"加入conditionNames;
• vite-plugin-svelte最低 2.4.1(SvelteKit 用户升级到 1.20.0 以上即可);rollup-plugin-svelte最低 7.1.5;svelte-loader最低 3.1.8;
• 最低 TypeScript 版本为TypeScript 5(更低版本"可能可用但不保证");
• 移除svelte/register钩子、CJS 运行时版本与 CJS 编译器输出——Svelte 从此纯 ESM,需要 CJS 的项目得靠打包器在构建后转译;
• createEventDispatcher、Action/ActionReturn、onMount的类型收紧(见 3.2 与 v4 迁移指南 中的对照代码);
• 自定义元素(custom elements)创建方式全面重构,<svelte:options tag="...">被customElement="..."取代;
• SvelteComponentTyped被废弃,由能力完整的SvelteComponent取代。

3.2 运行时行为变化

• 转场(transition)默认变为local:当嵌套控制流块(each/if/await/key)的上级块创建/销毁时,不再播放转场,避免页面导航时的困惑;需要旧行为时加|global修饰符;
• 传给derived的 falsy 值(而非 store)会直接抛错;
• 自行实现 store 者需要在writable等创建函数的StartStopNotifier回调中额外传入update函数(与set并列);
• 默认 slot 绑定不再暴露给命名 slot,反之亦然;
• preprocessor 应用顺序改变:现在按"数组顺序逐个执行,单个 preprocessor 内部按 markup → script → style"的顺序,且每个 preprocessor 必须有name;
• 运行时改用classList.toggle(name, boolean)与CustomEvent构造函数,非常老的浏览器需 polyfill;
• outro 中的元素会被加上inert属性,使其对辅助技术不可见且不可交互。

3.3 新增能力(Minor Changes)

4.0.0 同时引入了若干 3.x 末期呼声很高的特性,包括:

• data-svelte-h属性加速 hydration(检测未变化的 HTML 元素);
• 两条新的 a11y 规则:no-noninteractive-element-interactions与a11y-no-static-element-interactions;
• {#each}可迭代Set、Map等可迭代对象;
• 版本号写入window,可通过编译器选项discloseVersion: false关闭;
• 转场不再需要style-src 'unsafe-inline'CSP 指令;
• 样式表以/* empty */初始化,使 CSP 指令在 Safari 中也生效;
• preprocessor 获得修改 script/style 属性的能力。

3.4 4.x 补丁期(4.0.1 – 4.2.3)

4.0 发布后的收尾集中在三类问题,阅读时可按此线索检索:

• hydration 加固:@html标签改用非破坏性 hydration(4.0.2)、hydration 时检查srcset避免多余请求(4.0.2)、修复 raw html(4.0.4)、4.2.3 中"more robust hydration of html tag"收口;
• <svelte:element>的边界情况:动态this加 spread 属性(4.2.1)、slot 属性子元素(4.1.2)、spread 属性中的 option value 识别(4.2.1);
• 自定义元素与 a11y:自定义元素的 camelCase 属性(4.2.2)、prop 更新回写到 attribute(4.0.2)、a11y 点击事件提示优化(4.2.3)。

4.0.0 的四个预发布版本(4.0.0-next.0至next.3,L232-L266)记录了正式版的打磨过程,例如"在 window 中写入版本信息"与"更小的析构函数 chunk"均在 next 阶段先行落地。

四、源码佐证:changelog 条目在 5.x 仓库中的落点

虽然档案记录的是 5.0 之前的版本,但其中相当多条目在当前仓库的源码中仍能直接找到实现,可交叉验证:

• "版本信息写入 window"(4.0.0):当前实现见 disclose-version.js,全部逻辑仅六行——

  if (typeof window !== 'undefined') { // @ts-expect-error ((window.__svelte ??= {}).v ??= new Set()).add(PUBLIC_VERSION); }

  使用Set记录版本集合,说明 Svelte 支持同页多版本共存(同一 window 下多个 Svelte 实例各登记一次版本号)。

• svelteHTML类型(4.2.0):核心入口类型文件为 packages/svelte/svelte-html.d.ts,与 changelog 中"movesvelteHTMLfrom language-tools into core to load the correctsvelte/elementtypes"一致。

• legacy 运行时的保留:4.x 时代的行为在 5.x 中并未消失,而是被显式隔离在 src/internal/legacy.js 与 src/legacy/ 目录中,供 legacy mode(非 runes 组件)继续工作。这也解释了为什么维护 3.x/4.x 项目的开发者可以把这份 changelog 与 06-v4-migration-guide.md 配合使用。

• 迁移工具链:v4 迁移指南给出的官方自动迁移命令为npx svelte-migrate@latest svelte-4,可自动处理tag→customElement、SvelteComponentTyped→SvelteComponent、转场加|global等改动;迁移范围与 changelog 中标注 "see PR for migration instructions" 的条目一一对应。

五、实战:如何用这份档案定位问题

以下操作只涉及查看与检索,不修改仓库内容:

1. 确认某特性引入版本:直接按特性名检索,例如

   grep -n "svelte:element" packages/svelte/CHANGELOG-pre-5.md

   首条命中的 3.47.0 即为<svelte:element>的引入版本,后续 3.51.0、3.56.0 等条目记录了它对 SVG、scoped style 的逐步支持。

2. 排查老项目的版本行为差异:锁定项目所用版本(如 3.55.0),阅读对应小节即可知道当次发布的全部变更;若问题跨越多个小版本,从新到旧逐段回溯,changelog 按时间倒序排列,越靠后的版本越接近文件开头。

3. 理解某次 breaking change 的完整上下文:先读 changelog 条目(如 4.0.0 的浏览器条件要求),再读 v4 迁移指南 中"Browser conditions for bundlers"一节的 Rollup/webpack 具体配置,两处互为印证。

4. 判断升级路径的约束:从 3.x 升 4.x 需先满足 Node 16 + webpack 5/Rollup 插件最低版本 + TS 5 的环境约束;从 4.x 升 5.x 则属于 runes 时代重写,应改查 CHANGELOG.md 与 v5 迁移指南,本档案不再覆盖。

六、小结

CHANGELOG-pre-5.md 不只是一份更新日志,而是 Svelte 在 5.0 之前约九年开发史的技术索引:0.x 的占位与 TodoMVC 首秀、1.x 的 SSR 与 preprocess、2.x 的模板语法换轨、3.x 的位掩码状态机与{@const}/<svelte:element>增量扩展、4.x 面向 ESM 纯量化的彻底清理,每个阶段的决策都能在文件里找到原始条目与 PR 编号。对于维护 3.x/4.x 遗留项目的开发者,它是定位"功能何时可用、行为何时改变"的第一手依据;对于理解当前 5.x 源码为何如此组织(如 legacy 目录的存在、data-svelte-hhydration 机制),它同样提供了不可缺少的历史坐标。

【免费下载链接】svelteweb development for the rest of us项目地址: https://gitcode.com/GitHub_Trending/sv/svelte