React-Query Mutation未触发onSuccess/onError/onSettled副作用排查

可能的原因及解决方法 #

1. 确认Mutation实例的有效性 #

确保你是在**组件内部正确调用useRegisterUserMutation()**获取mutation实例，且组件处于挂载状态，没有被条件渲染提前卸载。如果组件在调用mutate后立即卸载，回调函数会因组件销毁而无法执行。

2. 检查服务端错误是否转为Promise拒绝 #

React-Query的onError只有在mutationFn返回的Promise被拒绝时才会触发。如果你的UserServiceInstance.register在服务端返回错误时没有抛出异常（比如axios拦截器自定义了错误处理但未重新抛出），React-Query会认为mutation成功，不会进入错误回调。

可以手动在mutationFn中处理响应，确保错误被抛出：

export const useRegisterUserMutation = () => {
  return useMutation({
    mutationFn: async (data: SignedMessageType) => {
      const response = await UserServiceInstance.register(data);
      // 根据接口返回结构判断是否为错误
      if (response.status >= 400 || !response.success) {
        throw new Error(response.message || '注册失败');
      }
      return response;
    },
  });
};

3. 验证错误对象的结构是否匹配 #

你在onError中判断err.message === 'User exists'，但实际错误的信息可能不在err.message字段。比如axios抛出的错误，服务端返回的信息通常在err.response.data.message中。

先打印完整错误对象确认结构：

onError: (err: any) => {
  console.log('完整错误详情:', err); // 查看错误的真实结构
  // 调整判断逻辑，比如：
  if (err.response?.data?.message === 'User exists') {
    // 执行逻辑
  }
},

4. 排查全局错误处理的干扰 #

如果你的React-Query配置了全局onError，或者项目中有全局Promise捕获逻辑，可能会影响mutation级别的回调触发。虽然React-Query的全局和局部回调默认都会执行，但可以检查全局配置是否存在异常：

// 检查QueryClient的全局配置
const queryClient = new QueryClient({
  defaultOptions: {
    mutations: {
      onError: (err) => {
        console.log('全局错误:', err);
        // 无需重新抛出错误，React-Query会自动触发局部回调
      },
    },
  },
});

5. 确认React-Query版本兼容性 #

确保你使用的React-Query版本与代码写法匹配。v4版本的useMutation和mutate选项结构是正确的，但如果是v3版本，可确认版本是否正确，避免因版本差异导致的问题。

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