React Query在Monorepo架构中的上下文共享问题解析

问题背景

在使用React Query v5版本时，特别是在Turborepo等Monorepo架构中，开发者经常会遇到"Error: No QueryClient set, use QueryClientProvider to set one"的错误提示。这个问题的本质是React上下文(Context)在模块间的共享机制出现了问题。

核心原理

React Query内部使用React的Context API来共享QueryClient实例。当组件调用useQuery等钩子时，会尝试从最近的QueryClientProvider中获取QueryClient实例。在Monorepo架构中，如果存在以下情况，就会导致上下文无法正确共享：

1. 多个React版本共存
2. 多个React Query版本共存
3. 模块打包方式导致上下文隔离

典型场景分析

在Monorepo中，常见的触发场景包括：

1. 共享库和主应用使用了不同版本的React或React Query
2. 使用pnpm等包管理器时，peerDependencies解析策略导致模块隔离
3. Next.js等框架内置了特定React版本，与项目声明的版本冲突

解决方案

统一依赖版本

确保整个Monorepo中使用完全相同的React和React Query版本，包括：

• 主版本号
• 次要版本号
• 补丁版本号
• peerDependencies配置

集中管理QueryClient

推荐在共享库中同时导出QueryClient和QueryClientProvider，而不是仅仅导出自定义钩子。这样主应用可以显式地提供上下文。

// 在共享库中
export const queryClient = new QueryClient();
export { QueryClientProvider } from '@tanstack/react-query';

显式传递QueryClient

对于特殊情况，可以直接将QueryClient实例作为第二个参数传递给useQuery，绕过上下文机制：

useQuery(queryKey, queryFn, { queryClient });

最佳实践建议

1. 在共享库中将React和React Query声明为peerDependencies而非dependencies
2. 使用包管理器的workspace协议确保版本一致性
3. 考虑在Monorepo根目录安装共享依赖
4. 定期检查依赖树中的重复版本

深入理解

这个问题不仅限于React Query，任何使用React Context共享状态的库在Monorepo中都可能遇到类似问题。理解其根本原因有助于开发者更好地设计Monorepo架构和模块边界。

通过合理规划依赖关系和上下文提供方式，可以充分发挥React Query在复杂项目中的优势，同时避免上下文隔离带来的问题。