Redux Toolkit 2.2.7 版本修复 TypeScript ESM 模块声明问题分析

问题背景

在使用 Redux Toolkit 进行 TypeScript 开发时，当项目配置为 ESM 模块系统（moduleResolution 设置为 NodeNext、Node16 或 bundler）并启用声明文件生成（declaration: true）时，开发者会遇到类型推断相关的错误。这些错误通常表现为：

The inferred type of X cannot be named without a reference to '../../node_modules/@reduxjs/toolkit/dist/query/react/buildHooks'. This is likely not portable. A type annotation is necessary.

这类问题特别容易出现在以下场景：

• 创建包含 Redux Toolkit 操作的库
• 在 monorepo 中共享包
• 使用 composite 项目配置

技术原因分析

问题的根本原因在于 ESM 模块系统的严格性。与传统的 CommonJS 模块系统不同，ESM 不允许开发者访问未在 package.json 中显式导出的模块或文件。Redux Toolkit 的某些内部类型没有被显式导出，导致 TypeScript 在生成声明文件时无法正确引用这些类型。

具体来说，问题涉及以下几个方面：

1. 类型可见性问题：许多 RTK 内部类型（如 UseQuery 等）没有被显式导出
2. 模块解析差异：Node 模块解析可以工作，但 NodeNext/Node16/bundler 会失败
3. 声明文件生成机制：当 declaration: true 时，TypeScript 需要确保所有引用的类型都是可导出的

解决方案演进

Redux Toolkit 团队经过多次尝试和讨论，最终确定了以下解决方案路径：

1. 显式导出关键类型：确保所有被公共 API 使用的内部类型都有适当的导出路径
2. 重构类型声明结构：避免深层嵌套的类型引用链
3. 构建工具调整：考虑从 tsup 迁移到基于 Vite 的构建工具链以获得更好的类型处理能力

在 2.2.7 版本中，团队主要采用了第一种方案，通过显式导出所有必要的类型来解决兼容性问题。

开发者应对策略

在官方修复发布前，开发者可以采用以下临时解决方案：

1. 修改模块解析策略（不推荐长期方案）： 将 tsconfig.json 中的 moduleResolution 改为 "Node"

2. 手动补丁方案： 对于 pnpm/yarn 用户，可以通过 patch-package 修改 node_modules 中的类型声明文件，添加必要的导出语句

3. 类型定义调整： 将 interface 改为 type 声明有时可以绕过某些特定错误

最佳实践建议

1. 保持 Redux Toolkit 更新：确保使用 2.2.7 或更高版本
2. 检查类型导出：对于自定义的 API 响应类型，确保使用 export 显式导出
3. monorepo 注意事项：在跨包引用时特别注意类型可见性
4. 构建工具选择：对于复杂类型项目，考虑使用支持精细类型控制的构建工具

总结

Redux Toolkit 2.2.7 版本彻底解决了 ESM 模块系统下的类型声明问题，使开发者能够在现代 TypeScript 项目配置中无缝使用 RTK 的强大功能。这一改进特别有利于库开发者和 monorepo 用户，为他们提供了更好的类型安全性和开发体验。