Svelte 4 迁移指南：从版本3升级到版本4的全面解析

Svelte 4 迁移指南：从版本3升级到版本4的全面解析

svelte 网络应用的赛博增强。 项目地址: https://gitcode.com/gh_mirrors/sv/svelte

前言

Svelte 4作为框架的重要版本更新，带来了多项改进和优化。本文将全面解析从Svelte 3迁移到Svelte 4的关键变化点，帮助开发者顺利完成升级。我们将从环境要求、核心变更到具体API调整等多个维度进行详细说明。

环境要求升级

在迁移到Svelte 4之前，首先需要确保开发环境满足以下最低要求：

1. Node.js版本：必须升级到Node 16或更高版本，早期版本不再支持
2. 构建工具：
   • 如果使用webpack，需要升级到webpack 5+和svelte-loader 3.1.8+
   • 如果使用Rollup，需要升级到rollup-plugin-svelte 7.1.5+
3. TypeScript支持：建议升级到TypeScript 5+，低版本可能仍能工作但不保证稳定性

构建工具配置变更

Svelte 4对构建工具配置提出了新要求，特别是在浏览器环境下的模块解析：

1. 浏览器条件标识：构建前端包时，构建工具必须指定browser条件标识
   • Rollup用户需要在@rollup/plugin-node-resolve插件中设置browser: true
   • webpack用户需要在conditionNames数组中添加"browser"

这一变更确保了生命周期钩子如onMount能在浏览器环境下正确执行。

模块系统变更

Svelte 4移除了对CommonJS(CJS)格式的支持，包括：

1. 不再支持CJS格式的编译器输出
2. 移除了svelte/register钩子
3. 移除了CJS运行时版本

如果需要CJS输出，建议在构建流程的最后阶段使用打包工具将ESM转换为CJS。

类型系统强化

Svelte 4对多个核心API的类型定义进行了严格化处理：

事件分发器类型增强

createEventDispatcher现在支持更精确的事件负载类型定义：

const dispatch = createEventDispatcher<{
  optional: number | null;  // 可选参数
  required: string;        // 必需参数
  noArgument: null;        // 无参数
}>();

dispatch('optional');      // 正确
dispatch('required');      // 错误：缺少参数
dispatch('noArgument', 'surprise'); // 错误：不应传递参数

Action类型调整

Action相关类型现在默认参数类型为undefined，需要显式指定参数类型：

// 旧版
const action: Action = (node, params) => { ... } // 错误

// 新版
const action: Action<HTMLElement, string> = (node, params) => { ... } // params为string类型

onMount类型检查

onMount现在会检查异步返回的函数，因为这通常是代码错误：

// 错误示例(异步返回清理函数不会被执行)
onMount(async () => {
  const something = await foo();
  return () => cleanup(); // 不会被执行
});

// 正确写法
onMount(() => {
  foo().then(something => {...});
  return () => cleanup(); // 会被执行
});

自定义元素改进

Svelte 4对自定义元素支持进行了重大改进：

1. 废弃了tag选项，改用新的customElement选项
2. 属性更新时机有所调整
3. 提供了更丰富的配置选项

迁移示例：

<!-- 旧版 -->
<svelte:options tag="my-component" />

<!-- 新版 -->
<svelte:options customElement="my-component" />

组件类型统一

SvelteComponentTyped已被废弃，其功能已整合到SvelteComponent中：

// 旧版
import { SvelteComponentTyped } from 'svelte';
export class Foo extends SvelteComponentTyped<{ aProp: string }> {}

// 新版
import { SvelteComponent } from 'svelte';
export class Foo extends SvelteComponent<{ aProp: string }> {}

对于动态组件类型，需要添加类型参数：

let component: typeof SvelteComponent<any>; // 添加<any>类型参数

过渡动画行为变更

过渡动画现在默认是"local"的，只在直接父级控制流块创建/销毁时触发：

{#if show}
  {#if success}
    <p in:slide>Success</p> <!-- 仅在success变化时触发 -->
  {/if}
{/if}

如果需要全局行为，需显式添加|global修饰符：

<p in:slide|global>Global Transition</p>

插槽绑定作用域调整

默认插槽的绑定不再暴露给命名插槽，反之亦然：

<Nested let:count>
  <p>{count}</p>          <!-- 可用 -->
  <p slot="bar">{count}</p> <!-- 不可用 -->
</Nested>

这一变更使插槽绑定行为更加一致和可预测。

预处理器执行顺序变更

预处理器执行顺序调整为按处理器顺序依次执行各组件的标记、脚本和样式处理：

// Svelte 4执行顺序：
markup-1 → script-1 → style-1 → markup-2 → script-2 → style-2

如果使用MDsveX等工具，需要确保它位于其他脚本/样式预处理器之前。

其他重要变更

1. 辅助技术支持：inert属性现在会应用到正在退出的元素上
2. DOM操作优化：DOM节点移除操作现在是批量进行的
3. 派生存储改进：derived现在会对传入的非存储值抛出错误
4. 类型定义调整：移除了svelte/internal的类型定义，避免使用内部API
5. 全局类型命名空间：从svelte.JSX迁移到svelteHTML命名空间

迁移工具与策略

官方提供了迁移脚本来自动处理部分变更：

npx svelte-migrate@latest svelte-4

对于库开发者，需要评估是否同时支持Svelte 3和4，并更新peerDependencies中的版本范围。

结语

Svelte 4的变更加强了类型安全、改善了自定义元素支持，并优化了整体行为一致性。虽然迁移过程可能需要一些调整，但这些改进为开发者提供了更可靠和可维护的代码基础。建议开发者按照本文指南逐步进行迁移，充分利用新版本带来的优势。

svelte 网络应用的赛博增强。 项目地址: https://gitcode.com/gh_mirrors/sv/svelte