查询重试

更新于 2026-11-02 Svelte 查看英文原文 ↗

当 createQuery 查询失败（查询函数抛出错误）时，若该查询请求尚未达到连续重试次数上限（默认为 3 次），或你提供了用于判断是否允许重试的函数，TanStack Query 将自动重试该查询。

你可以在全局层面和单个查询层面分别配置重试行为。

设置 retry = false 将禁用重试。
设置 retry = 6 将在显示查询函数最终抛出的错误前，对失败请求重试 6 次。
设置 retry = true 将无限次重试失败请求。
设置 retry = (failureCount, error) => ... 可基于请求失败原因实现自定义逻辑。注意 failureCount 在首次重试尝试时从 0 开始计数。

在服务端，重试默认设为 0 次，以使服务端渲染尽可能快。

svelte

1<script lang="ts">2  import { createQuery } from '@tanstack/svelte-query'3 4  // Make a specific query retry a certain number of times5  const result = createQuery(() => ({6    queryKey: ['todos', 1],7    queryFn: fetchTodoListPage,8    retry: 10, // Will retry failed requests 10 times before displaying an error9  }))10</script>

说明：error 属性的内容将在 createQuery 的 failureReason 响应属性中持续存在，直至最后一次重试尝试。因此，在上述示例中，任何错误内容都将在前 9 次重试尝试（总计 10 次尝试）期间作为 failureReason 属性的一部分；若所有重试尝试后错误依然存在，则最终该错误内容将归入 error 属性。

重试延迟

默认情况下，TanStack Query 的重试不会在请求失败后立即发生。与标准实践一致，每次重试尝试都会逐步应用退避延迟（back-off delay）。

默认 retryDelay 设置为每次尝试时加倍（起始值为 1000ms），但不超过 30 秒：

svelte

1<script lang="ts">2  // Configure for all queries3  import { QueryClient, QueryClientProvider } from '@tanstack/svelte-query'4 5  const queryClient = new QueryClient({6    defaultOptions: {7      queries: {8        retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),9      },10    },11  })12</script>13 14<QueryClientProvider client={queryClient}>...</QueryClientProvider>

尽管不推荐，你显然可在 Provider 和单个查询选项中覆写 retryDelay（函数或整数值）。若将其设为整数而非函数，则每次重试延迟将保持固定：

svelte

1<script lang="ts">2  import { createQuery } from '@tanstack/svelte-query'3 4  const result = createQuery(() => ({5    queryKey: ['todos'],6    queryFn: fetchTodoList,7    retryDelay: 1000, // Will always wait 1000ms to retry, regardless of how many retries8  }))9</script>

后台重试行为

当配合 refetchInterval 使用 refetchIntervalInBackground: true 时，若浏览器标签页处于非活跃状态，重试将暂停。这是因为重试遵循与常规重新拉取（refetch）相同的焦点行为（focus behavior）。

若你需要后台持续重试，请考虑禁用重试并实现自定义重新拉取策略：

svelte

1<script lang="ts">2  import { createQuery } from '@tanstack/svelte-query'3 4  const result = createQuery(() => ({5    queryKey: ['todos'],6    queryFn: fetchTodos,7    refetchInterval: (query) => {8      // Refetch more frequently when in error state9      return query.state.status === 'error' ? 5000 : 3000010    },11    refetchIntervalInBackground: true,12    retry: false, // Disable built-in retries13  }))14</script>

此方法让你能手动控制重试时机，同时保持后台重新拉取的活跃状态。