devtools 中间件

相关源文件

• docs/middlewares/combine.md
• docs/middlewares/devtools.md
• docs/middlewares/redux.md
• docs/middlewares/subscribe-with-selector.md
• src/middleware/combine.ts
• src/middleware/devtools.ts
• src/middleware/immer.ts
• src/middleware/redux.ts
• src/middleware/subscribeWithSelector.ts
• tests/devtools.test.tsx

devtools 中间件将 Zustand 与 Redux DevTools Extension 集成，使您能够为 Store 实现强大的时间旅行调试功能，而无需 Redux 本身。此中间件会拦截状态更改，将其发送到 Redux DevTools，并启用时间旅行调试、操作检查和状态历史可视化等完整的 DevTools 功能。

有关 Zustand 中间件的常规信息，请参阅 中间件系统。

概述

来源： src/middleware/devtools.ts177-201 src/middleware/devtools.ts250-366

与 Redux DevTools 集成

devtools 中间件在您的 Zustand Store 和 Redux DevTools 之间创建了一个桥梁，使您能够

1. 可视化和跟踪所有状态更改
2. 在不同状态之间进行时间旅行
3. 从 DevTools UI 分派自定义操作
4. 将状态重置为初始值
5. 提交和回滚状态更改

连接流程

来源： src/middleware/devtools.ts112-147 src/middleware/devtools.ts177-201 src/middleware/devtools.ts250-366

安装与设置

要使用 devtools 中间件，您需要

1. 在浏览器中安装 Redux DevTools Extension
2. 将中间件导入并应用到您的 Zustand Store

来源： docs/middlewares/devtools.md66-95 src/middleware/devtools.ts177-201 src/middleware/devtools.ts250-366

API 参考

devtools 中间件

参数

1. stateCreatorFn： 定义 Store 状态和操作的状态创建函数
2. devtoolsOptions： Redux DevTools 集成的配置选项

DevtoolsOptions

选项	类型	默认	描述
名称	字符串	未定义	DevTools 连接的自定义标识符
enabled	布尔值	开发环境中为 true，生产环境中为 false	启用/禁用 DevTools 集成
anonymousActionType	字符串	'anonymous'	未命名操作的操作类型
store	字符串	未定义	在多 Store 设置中，特定 Store 的自定义标识符

来源： src/middleware/devtools.ts71-76 src/middleware/devtools.ts78-86

增强的 setState

devtools 中间件通过添加一个可选的第三个参数来为操作命名，从而增强了标准的 setState 方法。

这使得可以为状态更改赋予有意义的名称，这些名称会显示在 Redux DevTools 中。

来源： src/middleware/devtools.ts52-69 src/middleware/devtools.ts178-202

主要功能

操作跟踪

每次状态更改都会在 Redux DevTools 中被跟踪为一个操作。操作可以

1. 通过 setState 的第三个参数命名
2. 匿名（使用通过 anonymousActionType 配置的默认名称）
3. 具有类型和其他元数据的复杂对象

来源： src/middleware/devtools.ts177-201

时间旅行调试

该中间件通过 Redux DevTools 支持完整的时间旅行调试

• JUMP_TO_STATE/JUMP_TO_ACTION： 将 Store 状态临时设置为历史状态
• RESET： 将 Store 恢复到初始状态
• COMMIT： 将当前状态设为新的参考点
• ROLLBACK： 恢复到上一个提交的状态
• IMPORT_STATE： 加载先前导出的状态

来源： src/middleware/devtools.ts305-366

Redux 兼容性

当与 redux 中间件一起使用时，devtools 允许从 Redux DevTools UI 分派操作

来源： src/middleware/redux.ts34-49 tests/devtools.test.tsx561-623

多 Store 支持

devtools 中间件提供了两种调试多个 Store 的方法

1. 分离的 DevTools 连接

默认情况下，每个 Store 都会获得自己的 Redux DevTools 连接

使用 Redux DevTools 中的 Store 选择器在 Store 之间切换。

2. 带命名 Store 的组合视图

使用 name 和 store 选项，您可以将多个 Store 分组到单个 DevTools 连接下

这会在单个 DevTools 实例中显示两个 Store，每个 Store 的状态都嵌套在其 Store 名称下。

来源： src/middleware/devtools.ts112-147 tests/devtools.test.tsx689-899

最佳实践

1. 始终为操作命名

不要依赖匿名操作，请提供有意义的名称

来源： docs/middlewares/devtools.md162-267

2. 对复杂的 Store 使用命名空间

在使用 slice 模式或多个模块时，为操作添加命名空间以区分它们

来源： docs/middlewares/devtools.md98-153

3. 只在开发环境中启用

为避免生产环境的性能影响，请有条件地启用中间件

默认情况下，中间件会检查 import.meta.env?.MODE !== 'production'，但明确设置 enabled 更可靠。

来源： src/middleware/devtools.ts163-165

故障排除

仅可见一个 Store

问题： 使用多个 Store 时，Redux DevTools 中只显示一个。

解决方案： Redux DevTools 默认一次显示一个 Store。使用 Redux DevTools 界面的 Store 选择器下拉列表在 Store 之间切换。

来源： docs/middlewares/devtools.md157-160

匿名操作

问题： 操作在 Redux DevTools 中显示为“anonymous”。

解决方案： 将操作名称作为第三个参数传递给 setState

来源： docs/middlewares/devtools.md162-268

Redux DevTools 未连接

问题： 尽管应用了中间件，但未连接到 Redux DevTools。

解决方案:

1. 确保已在浏览器中安装 Redux DevTools Extension
2. 检查 enabled 选项是否被错误地设置为 false
3. 尝试通过 name 选项使用显式的连接名称
4. 检查浏览器控制台中的连接错误

来源： src/middleware/devtools.ts159-168

相关中间件

devtools 中间件与其它 Zustand 中间件配合得特别好

• redux 中间件： 用于 Redux 风格的操作和 reducers（完全支持从 DevTools 分派）
• immer 中间件：用于简化的不可变状态更新
• persist 中间件：用于跨会话持久化状态

来源： tests/devtools.test.tsx561-623