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

在 SvelteKit 项目中结合使用 Svelte-Query 时，开发者可能会遇到一个看似奇怪的问题：当在布局文件(layout.ts)中访问 URL 对象时，prefetchQuery 的缓存功能会失效。本文将深入分析这一现象的原因，并提供解决方案。

问题现象

当开发者在 SvelteKit 的根布局文件(+layout.ts)中使用 prefetchQuery 进行数据预取时，如果同时访问了 load 函数参数中的 url 对象，会出现以下异常行为：

1. 鼠标悬停在列表项上时，每次都会发起新的网络请求，而不是使用缓存
2. 点击进入详情页时，会重复请求相同的数据
3. 查询开发工具显示缓存未生效

根本原因

这一问题的根源在于 SvelteKit 的响应式加载机制。当布局文件中访问了 url 对象时，SvelteKit 会在每次路由变化时重新执行该布局的 load 函数，导致：

1. 每次路由变化都会创建新的 QueryClient 实例
2. 不同 QueryClient 实例之间无法共享缓存
3. 预取的数据实际上被存储在了临时的 QueryClient 中，随后被丢弃

技术细节

在 SvelteKit 架构中，布局文件具有特殊的行为：

1. 根布局文件通常用于初始化全局状态
2. 如果布局的 load 函数不依赖任何响应式数据(如 url)，SvelteKit 会优化为只执行一次
3. 一旦访问了 url 等响应式数据，就会变成响应式加载，随路由变化而重新执行

QueryClient 的设计是维护一个内部的缓存存储，当创建新实例时，之前的缓存自然无法访问。

解决方案

要解决这个问题，可以采用以下最佳实践：

1. 分离初始化逻辑：将 QueryClient 的创建与响应式逻辑分离
2. 避免在根布局中使用响应式数据：将 url 相关的逻辑下放到页面级或子布局中
3. 保持 QueryClient 实例稳定：确保它不会被频繁重建

修正后的代码结构应该是：

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

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

  return { queryClient }
}

而将 url 相关的逻辑移动到具体的页面文件中：

// +page.ts
import type { PageLoad } from "./$types"

export const load: PageLoad = async ({ url }) => {
  console.log(url.pathname)
  // 页面特定的逻辑
}

性能优化建议

1. 对于需要预取的数据，考虑在页面级而非布局级进行
2. 对于全局共享的数据，可以使用顶层提供 context 的方式
3. 合理设置 staleTime 和 cacheTime 以平衡新鲜度和性能
4. 考虑使用 SvelteKit 的预加载特性与 Svelte-Query 配合

总结

这个问题很好地展示了框架特性之间的微妙交互。SvelteKit 的响应式加载机制与 Svelte-Query 的缓存设计需要合理配合才能发挥最佳性能。理解这些底层机制有助于开发者构建更高效、更可靠的应用程序。

通过将初始化逻辑与响应式逻辑分离，我们既能保持框架提供的便利性，又能充分利用 Svelte-Query 的强大缓存功能，实现最佳的用户体验。