React Query ESLint 插件与 ESLint v9 的兼容性问题分析

问题背景

React Query 是一个流行的 React 数据获取库，其配套的 ESLint 插件 @tanstack/eslint-plugin-query 旨在帮助开发者遵循最佳实践。然而，当开发者尝试在 ESLint v9 环境中使用该插件的 v4 版本时，会遇到两个主要问题：

1. 安装时出现依赖不匹配错误，必须使用 --force 或 --legacy-peer-deps 标志才能完成安装
2. 即使安装成功，运行时会出现 TypeError: t.getAncestors is not a function 的错误

技术原因分析

依赖版本限制

@tanstack/eslint-plugin-query@4 的 package.json 中明确指定了 peerDependencies：

"peerDependencies": {
  "eslint": "^6.0.0 || ^7.0.0 || ^8.0.0"
}

这意味着该插件官方仅支持 ESLint 6.x 到 8.x 版本。ESLint v9 引入了许多重大变更，包括 API 的调整，这正是导致 getAncestors 方法不可用的原因。

版本演进策略

React Query 团队遵循了常见的开源维护策略：主要版本线（如 v4）通常只接收关键的安全修复和错误修正，而不会添加对新依赖版本的支持。这种策略有助于维护稳定性，同时鼓励用户升级到最新主要版本。

解决方案

对于需要使用 ESLint v9 的开发者，有以下几种选择：

1. 升级到 React Query v5：这是官方推荐的做法。v5 版本的 ESLint 插件完全支持 ESLint v9，且包含更多现代化规则。

2. 降级 ESLint 版本：如果不急于升级 ESLint，可以暂时使用 ESLint 8.x 版本，直到准备好全面升级。

3. 自行维护分支：技术能力较强的团队可以 fork v4 插件并自行适配 ESLint v9，但这会增加长期维护成本。

最佳实践建议

1. 版本一致性：在大型项目中，应确保所有工具链的主要版本相互兼容。ESLint 插件通常需要与 ESLint 主版本保持同步。

2. 升级路径规划：从 React Query v4 升级到 v5 时，建议先升级 ESLint 插件，利用其规则识别需要修改的代码模式。

3. 理解破坏性变更：ESLint v9 的 API 变更影响了插件架构，这种重大版本升级通常需要插件作者重写部分代码逻辑。

总结

React Query 生态系统的版本策略体现了现代前端工具链的维护理念：鼓励用户保持最新，同时为旧版本提供有限支持。开发者在规划技术栈升级时，应当考虑工具间的相互依赖性，特别是像 ESLint 插件这类深度集成的工具。对于正在从 React Query v4 迁移到 v5 的团队，建议将 ESLint 升级纳入整体迁移计划，以获得最佳的开发体验和最新的功能支持。