Svelte-Query 中 prefetchQuery 缓存失效问题的深度解析

问题现象

在使用 SvelteKit 和 Svelte-Query 组合开发时，开发者发现了一个有趣的缓存失效问题：当在根布局文件 +layout.ts 中访问 url 对象时，prefetchQuery 的缓存功能会完全失效。具体表现为：

1. 鼠标悬停在列表项上时，每次都会发起新的网络请求，而不是使用缓存
2. 点击进入详情页时，会重复请求相同数据
3. 移除 url 对象的访问后，缓存功能恢复正常

技术背景

在深入分析问题前，我们需要了解几个关键技术点：

1. SvelteKit 的布局加载机制：SvelteKit 的布局系统允许在多个页面间共享 UI 和逻辑。根布局 (+layout.svelte 和 +layout.ts) 是所有页面的基础。

2. QueryClient 的作用：Svelte-Query 的 QueryClient 是查询缓存的核心管理对象，负责存储、检索和管理所有查询状态。

3. prefetchQuery 的工作原理：预取查询会在实际需要数据前提前获取并缓存数据，优化用户体验。

问题根源

问题的本质在于 QueryClient 实例的重复创建。当在根布局的 load 函数中访问 url 对象时：

1. SvelteKit 会将 url 视为响应式依赖
2. 每次路由变化时，都会触发 load 函数的重新执行
3. 每次执行都会创建新的 QueryClient 实例
4. 新的 QueryClient 实例拥有独立的缓存系统
5. 之前预取的数据存在于旧的 QueryClient 实例中，无法被新实例访问

解决方案

基于对问题的理解，我们有以下几种解决方案：

方案一：避免在根布局中使用路由相关数据

将 url 相关的逻辑下放到具体的页面或子布局中：

// +layout.ts
import { QueryClient } from "@tanstack/svelte-query"
import type { LayoutLoad } from "./$types"
import { browser } from "$app/environment"

export const load: LayoutLoad = async () => {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        enabled: browser,
        staleTime: 60 * 1000,
      },
    },
  })

  return { queryClient }
}

方案二：使用单例模式管理 QueryClient

通过模块级变量确保始终使用同一个 QueryClient 实例：

// src/lib/queryClient.ts
import { QueryClient } from "@tanstack/svelte-query"
import { browser } from "$app/environment"

let queryClient: QueryClient

export function getQueryClient() {
  if (!queryClient) {
    queryClient = new QueryClient({
      defaultOptions: {
        queries: {
          enabled: browser,
          staleTime: 60 * 1000,
        },
      },
    })
  }
  return queryClient
}

然后在布局中使用：

// +layout.ts
import { getQueryClient } from "$lib/queryClient"
import type { LayoutLoad } from "./$types"

export const load: LayoutLoad = async () => {
  const queryClient = getQueryClient()
  return { queryClient }
}

最佳实践建议

1. QueryClient 应该作为单例：在整个应用生命周期中保持唯一实例，确保缓存共享。

2. 合理划分布局层级：

   • 根布局处理全局共享状态
   • 子布局处理特定路由组的状态
   • 页面组件处理具体页面的状态

3. 注意 SvelteKit 的响应式依赖：

   • url、params、data 等都会触发 load 函数的重新执行
   • 对于不常变化的数据，考虑使用 depends 函数明确声明依赖

4. 缓存策略优化：

   • 设置合理的 staleTime 和 cacheTime
   • 对于关键数据，考虑使用持久化缓存

总结

这个问题很好地展示了 SvelteKit 响应式系统与状态管理库交互时可能出现的边界情况。理解框架和库的内部工作机制，能够帮助我们写出更健壮、高效的代码。在 SvelteKit 生态中，合理组织代码结构、明确状态的生命周期管理，是构建高性能应用的关键。