React Query能否设置请求超时？超时后终止网络请求

React Query 本身没有直接提供「超时自动终止请求」的配置项，但可以通过 AbortController 结合查询函数（queryFn）来实现这个需求，这也是官方推荐的处理可取消请求的标准方式。

用 AbortController 实现超时终止 #

核心思路是在 queryFn 内部创建 AbortController 实例，设置超时定时器，超时后调用 controller.abort() 终止请求，同时将控制器的 signal 传入请求方法（fetch/axios），让请求能响应终止信号。

示例1：结合 Fetch API #

import { useQuery } from '@tanstack/react-query';

const fetchData = async () => {
  const controller = new AbortController();
  const signal = controller.signal;

  // 设置5秒超时时间
  const timeoutId = setTimeout(() => {
    controller.abort();
  }, 5000);

  try {
    const response = await fetch('https://api.example.com/data', { signal });
    if (!response.ok) throw new Error('请求失败');
    return await response.json();
  } catch (error) {
    // 区分超时终止的错误，做自定义处理
    if (error.name === 'AbortError') {
      throw new Error('请求超时，已自动终止');
    }
    throw error;
  } finally {
    // 清理定时器，避免内存泄漏
    clearTimeout(timeoutId);
  }
};

const MyComponent = () => {
  const { data, error, isLoading } = useQuery({
    queryKey: ['data'],
    queryFn: fetchData,
  });

  return (
    <div>
      {isLoading && <p>加载中...</p>}
      {error && <p>{error.message}</p>}
      {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
    </div>
  );
};

示例2：结合 Axios #

Axios 同样支持 AbortController 的 signal 参数，实现逻辑和 Fetch 类似：

import { useQuery } from '@tanstack/react-query';
import axios from 'axios';

const fetchDataWithAxios = async () => {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => {
    controller.abort();
  }, 5000);

  try {
    const response = await axios.get('https://api.example.com/data', {
      signal: controller.signal,
    });
    return response.data;
  } catch (error) {
    if (axios.isCancel(error)) {
      throw new Error('请求超时，已自动终止');
    }
    throw error;
  } finally {
    clearTimeout(timeoutId);
  }
};

// 组件中使用方式与上述示例一致

其他替代方案 #

如果不想在每个 queryFn 里重复写超时逻辑，可以考虑以下方式：

• 封装全局请求工具：把超时+AbortController的逻辑封装到统一的 fetch/axios 工具函数中，所有 React Query 的请求都调用这个工具，减少重复代码。
• Axios 原生超时（注意局限性）：Axios 自带 timeout 配置，但它只是超时后抛出错误，并不会真正终止底层的 HTTP 请求，必须结合 AbortController 才能实现请求的彻底终止。

内容的提问来源于stack exchange，提问作者helen8297