企业官网建设流程全解析

如何把 @tanstack/svelte-query 升级到 v6：runes 改写与 Svelte 5.25.0 要求

【免费下载链接】query🤖 Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query

如果你在用 Svelte 项目里使用@tanstack/svelte-queryv5，现在要升级到 v6，核心改动只有一件事：v6 适配器从 stores 语法全面迁移到了 runes（signals）语法。迁移文档 migrate-from-v5-to-v6.md 明确说明，Svelte v5 虽然对 v3/v4 的 stores 语法有兼容模式，但对该适配器而言“buggy and unreliable”，因此 v6 不再走 stores，而是基于 runes 重写。这个改写同时简化了让 query 输入保持响应式所需的代码。

适用前提：项目使用 Svelte v5.25.0 或更新版本。CHANGELOG 中 6.0.0 的条目写得很直接：BREAKING: Migrate to svelte runes (signals). Requires Svelte v5.25.0 or newer。

升级前确认 Svelte 版本

v6 对 Svelte 版本有硬性要求。两个来源可以核对：

• 迁移文档要求：Please ensure your project has Svelte v5.25.0 or newer；
• packages/svelte-query/package.json 中声明了peerDependencies："svelte": "^5.25.0"（当前包版本为 6.1.48）。

先在项目里确认svelte依赖版本满足^5.25.0。另一个相关事实：@tanstack/svelte-queryv6 依赖@tanstack/query-corev5，安装 v6 时会一并带入，不需要你手动处理。

安装 v6

迁移文档给出的安装命令（pnpm 为例）：

pnpm add @tanstack/svelte-query@latest

如果你用其他包管理器，文档说“or your package manager's equivalent”。安装文档列出的等价形式有：

npm i @tanstack/svelte-query yarn add @tanstack/svelte-query bun add @tanstack/svelte-query

改写一：函数入参必须包成 thunk

v6 中，Svelte 适配器的大部分函数要求把 options 以 thunk 的形式传入（() => options），以提供响应式。迁移文档指出 TypeScript 会帮你检查这一点——漏掉函数包装时会收到类型警告。

createQuery的改写前后对比（摘自迁移文档，-/+表示改动行）：

- const query = createQuery({ + const query = createQuery(() => ({ queryKey: ['todos'], queryFn: () => fetchTodos(), - }) + }))

概览文档中的完整组件写法（升级后应长成这样）：

<script lang="ts"> import { QueryClient, QueryClientProvider } from '@tanstack/svelte-query' import Example from './lib/Example.svelte' const queryClient = new QueryClient() </script> <QueryClientProvider client={queryClient}> <Example /> </QueryClientProvider>

<script lang="ts"> import { createQuery } from '@tanstack/svelte-query' const query = createQuery(() => ({ queryKey: ['todos'], queryFn: () => fetchTodos(), })) </script> <div> {#if query.isPending} <p>Loading...</p> {:else if query.isError} <p>Error: {query.error.message}</p> {:else if query.isSuccess} {#each query.data as todo} <p>{todo.title}</p> {/each} {/if} </div>

改写二：去掉属性访问前的$前缀

适配器不再使用 stores，所以模板中访问 query 属性时不再需要$前缀：

- {#if $todos.isSuccess} + {#if todos.isSuccess} <ul> - {#each $todos.data.items as item} + {#each todos.data.items as item} <li>{item}</li> {/each} </ul> {/if}

改写三：响应式输入改用$state

v5 里为了给 query 输入做响应式，需要借助writable+derived这类 stores 技巧；v6 不再需要，$state值可以直接传给 options，query 会自动更新：

- const intervalMs = writable(1000) + let intervalMs = $state(1000) - const query = createQuery(derived(intervalMs, ($intervalMs) => ({ + const query = createQuery(() => ({ queryKey: ['refetch'], queryFn: async () => await fetch('/api/data').then((r) => r.json()), - refetchInterval: $intervalMs, + refetchInterval: intervalMs, - }))) + }))

Quick Start补充了同类型示例：let enabled = $state(false)这样的 runes 值直接写进enabled: enabled是安全的，值变化时 observer 会自动更新；enabled: todoCount > 0这类表达式形式也可以。

禁用 legacy 模式，确保组件运行在 runes 模式

如果某个组件里还残留 stores，它可能无法正确切换到 runes 模式。迁移文档给出两种确保方式，按迁移节奏选用：

逐文件启用（适合大项目的渐进式迁移）：每个完成 runes 改写的.svelte文件里加上：

<svelte:options runes={true} />

全项目启用（可选分支，收尾阶段做）：当你 100% 清除了 stores 语法之后，在svelte.config.js中加入：

compilerOptions: { runes: true, }

迁移文档的原话是逐文件方式“better for large applications requiring gradual migration”，全项目开关要等 stores 语法彻底清除后再加。

如何验证升级完成

迁移文档给出的验证手段是把 TypeScript 作为检查器：thunk 写法漏掉时会有类型报错，所以升级后对整个项目跑一遍类型检查，重点看createQuery、createInfiniteQuery、createMutation等调用处是否都补上了() => (...)。仓库内该包自身的类型检查脚本是svelte-check --tsconfig ./tsconfig.json（见 packages/svelte-query/package.json 的test:types），你可以在项目里用对应的 svelte-check 命令做同样的检查；行为测试则对应test:lib脚本使用的vitest。

运行时再对照文档给出的成功形态：组件挂载后，query 走isPending→isSuccess/isError分支，且修改$state输入（如intervalMs）时 query 自动更新，无需额外的$derived包装。

升级后要记住的两个限制

• 不支持解构：Quick Start明确说明 Svelte Query 原语不支持解构，返回值是 proxy，属性在响应式上下文中动态解析。const { isPending, data } = createQuery(...)这种 React 习惯写法不可用，必须保持query.isPending这样的访问方式。
• notifyOnChangeProps不再需要：属性跟踪由 Svelte 的细粒度响应式处理，这个选项在 v6 场景下没有作用，可以直接删掉。

另外，错误处理可以改用 Svelte 原生的<svelte:boundary>组件捕获，配合throwOnError: true选项把错误抛到 boundary——这属于 runes 时代的推荐做法，迁移文档本身没有展开，按 Quick Start 的说明处理即可。

【免费下载链接】query🤖 Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query