译零 TransZero · TanStack Query 中文文档
主站

查询重试

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

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

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

  • 设置 retry = false 将禁用重试。
  • 设置 retry = 6 将在显示查询函数最终抛出的错误前,重试失败的请求 6 次。
  • 设置 retry = true 将无限次重试失败的请求。
  • 设置 retry = (failureCount, error) => ... 可基于请求失败原因实现自定义逻辑。注意:failureCount 在首次重试尝试时从 0 开始计数。
TypeScript
1import { injectQuery } from '@tanstack/angular-query-experimental'2 3// Make a specific query retry a certain number of times4const todoQuery = injectQuery(() => ({5  queryKey: ['todos', 1],6  queryFn: fetchTodoListPage,7  retry: 10, // Will retry failed requests 10 times before displaying an error8}))

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

重试延迟

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

默认 retryDelay 设置为每次尝试时延迟时间翻倍(起始值为 1000ms),但不超过 30 秒:

TypeScript
1// Configure for all queries2import {3  QueryCache,4  QueryClient,5  provideTanStackQuery,6} from '@tanstack/angular-query-experimental'7 8const queryClient = new QueryClient({9  defaultOptions: {10    queries: {11      retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),12    },13  },14})15 16bootstrapApplication(AppComponent, {17  providers: [provideTanStackQuery(queryClient)],18})

尽管不推荐,你仍可在插件(Plugin)和单个查询选项中显式覆盖 retryDelay(函数或整数值)。若将其设为整数而非函数,则每次重试延迟时间将保持恒定:

TypeScript
1const todosQuery = injectQuery(() => ({2  queryKey: ['todos'],3  queryFn: fetchTodoList,4  retryDelay: 1000, // Will always wait 1000ms to retry, regardless of how many retries5}))

后台重试行为

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

如果你需要后台持续重试,请考虑禁用重试并实现自定义的重新拉取策略:

TypeScript
1const result = injectQuery({2  queryKey: ['todos'],3  queryFn: fetchTodos,4  refetchInterval: (query) => {5    // Refetch more frequently when in error state6    return query.state.status === 'error' ? 5000 : 300007  },8  refetchIntervalInBackground: true,9  retry: false, // Disable built-in retries10})

该方法使你能够手动控制重试时机,同时确保后台的重新拉取保持活跃。

本页为 TanStack Query 文档(Angular 版)的非官方中文翻译,原文由上游团队维护,遵循 MIT 许可。 译文如有偏差,以英文原文为准。

译自上游 59d11de