TanStack Query在NX Monorepo中的QueryClient问题解析与解决方案

问题背景

在使用NX Monorepo架构开发React Native应用时，许多开发者遇到了一个棘手的问题：在开发模式下一切正常，但在构建生产版本APK后，应用会抛出"Error: No QueryClient set, use QueryClientProvider to set one"的错误。这个问题特别容易出现在将TanStack Query相关代码分离到独立库中的场景。

问题本质分析

这个问题的根源在于React Context的工作机制。TanStack Query通过React Context来管理QueryClient的全局状态，当出现以下情况时会导致Context无法正常工作：

1. 版本冲突：当项目中存在多个不同版本的React或TanStack Query时，即使版本号相同但来自不同的node_modules位置，也会被React视为不同的Context提供者。

2. 构建隔离：在Monorepo中，不同库和应用可能被独立构建，导致最终产物中出现重复的依赖包。

3. 开发与生产差异：开发模式下由于热更新和不同的打包策略，可能掩盖了这些问题，而生产构建会暴露这些问题。

解决方案

方案一：统一依赖管理

确保整个Monorepo中所有项目使用完全相同的React和TanStack Query版本。可以通过以下方式实现：

1. 在根目录的package.json中声明peerDependencies
2. 使用workspace协议确保所有项目引用相同的依赖版本
3. 定期运行依赖检查工具确保没有版本冲突

方案二：集中QueryClient管理

将所有与TanStack Query相关的代码集中到一个共享库中：

1. 创建一个专门的hooks库
2. 在该库中统一导出QueryClientProvider
3. 应用层只从这个库引入QueryClient相关组件

这种架构不仅解决了Context问题，还提高了代码的可维护性。

方案三：构建配置优化

检查NX和Expo的构建配置：

1. 确保构建时正确处理peerDependencies
2. 检查是否有依赖被错误地打包多次
3. 考虑使用NX的依赖优化功能

最佳实践建议

1. 单一职责原则：将与状态管理相关的代码集中管理，避免分散在多个库中。

2. 版本锁定：使用package-lock.json或yarn.lock确保依赖版本一致。

3. 构建验证：在CI流程中加入生产构建检查，尽早发现问题。

4. 架构评审：在项目初期规划好Monorepo中各库的职责边界。

总结

TanStack Query在NX Monorepo中出现的QueryClient问题，本质上是Monorepo架构下依赖管理和构建隔离带来的挑战。通过统一依赖版本、集中管理状态相关代码以及优化构建配置，可以有效解决这类问题。这不仅适用于TanStack Query，也是处理其他基于React Context的库时的通用解决方案。

对于大型项目，建议在架构设计阶段就考虑这些因素，建立完善的依赖管理策略和构建流程，避免后期出现难以调试的问题。