NgRx Store Devtools 完全指南:安装、配置与源码级原理解读
NgRx Store Devtools 完全指南:安装、配置与源码级原理解读
@ngrx/store-devtools 是 @ngrx/store 官方提供的开发者工具与运行时仪表化(instrumentation)模块,它把应用内每一个 dispatch 的 action 与对应状态变化记录为可回溯的历史树,并与 Redux Devtools 浏览器扩展打通,实现时间旅行调试、action 跳转、状态导入导出、测试生成等能力。读完本文,你将掌握如何通过 provideStoreDevtools 完成 Standalone / bootstrapApplication 场景下的接入,理解 maxAge、logOnly、autoPause、connectInZone、actionCreators 等全部配置项的真实语义与默认值,并能够结合源码理解其底层实现,同时在生产构建中正确剔除 Devtools。
@ngrx/store-devtools 是什么
Store Devtools 为 Store 提供开发者工具与仪表化能力。它的核心思路是"提升(lift)"整个 Store:在应用 Store 之上再构建一层被称为 lifted state(提升状态)的历史记录结构,用于保存每一次 action 与对应的状态快照、当前索引、被跳过或锁定的 action 等元数据。
这一设计在源码中有清晰体现:
- devtools.ts 中的
StoreDevtools服务通过liftInitialState与liftReducerWith构造提升状态与提升 reducer,再用scan算子把每次 action 的归约结果连同liftedState一起推进历史树; - utils.ts 中的
unliftState负责把提升状态还原为应用视角的普通状态,供StateObservable暴露给应用; - extension.ts 中的
DevtoolsExtension负责与浏览器扩展建立window.postMessage连接,双向转发 action 与状态。
因此,接入 Store Devtools 之后,你的应用状态流(dispatch → reducer → state)本身不受影响,Devtools 只是"旁路监听"并记录,这也是它能以极低侵入性用于调试的根本原因。
安装
通过 ng add 一键安装
在安装了 Angular CLI 的项目中执行:
ng add @ngrx/store-devtools@latest
该命令会自动完成以下步骤:
- 在
package.json的dependencies中加入@ngrx/store-devtools; - 运行
npm install安装依赖; - 在应用配置的 providers 中追加
provideStoreDevtools({ maxAge: 25, logOnly: !isDevMode() })(若指定了--maxAge标志,maxAge将取该值)。
ng add 还支持以下可选标志:
| 标志 | 说明 | 类型 | 默认值 |
|---|---|---|---|
--path |
希望为其添加 StoreDevtoolsModule 导入的模块路径 |
string |
— |
--project |
angular.json 中定义的项目名,用于定位要添加 StoreDevtoolsModule 的模块 |
string |
— |
--module |
包含目标模块的文件名,可含相对路径,例如 src/app/app.module.ts |
string |
app |
--maxAge |
历史树中最多保存的 action 数,超过后最旧的 action 会被移除,对性能至关重要;0 表示无限。取值必须大于 1 或等于 0 | number |
25 |
手动安装
也可以使用包管理器手动安装:
npm install @ngrx/store-devtools --save
# 或
yarn add @ngrx/store-devtools
# 或
pnpm add @ngrx/store-devtools
注意:Store Devtools 应当只在开发环境下使用,切勿在生产依赖中保留它(后文"生产排除"一节会给出具体做法)。
基础接入:Standalone 与 bootstrapApplication
Store Devtools 依赖浏览器扩展。在基于 bootstrapApplication 的 Standalone 应用(或 Angular 17+ 的 ApplicationConfig)中,先在浏览器安装 [Redux Devtools Extension],然后在 main.ts 中注入 provideStoreDevtools:
import { isDevMode } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import { provideStore } from '@ngrx/store';
import { provideStoreDevtools } from '@ngrx/store-devtools';
import { AppComponent } from './app.component';
bootstrapApplication(AppComponent, {
providers: [
provideStore(),
provideStoreDevtools({
maxAge: 25, // 最多保留最近 25 个状态
logOnly: !isDevMode(), // 生产环境限制扩展为仅日志模式
autoPause: true, // 扩展窗口未打开时暂停记录 action 与状态变化
trace: false, // 设为 true 时为每个 dispatch 的 action 记录堆栈,可在 trace 标签页直接跳到对应代码
traceLimit: 75, // trace 为 true 时最多保存的堆栈帧数
connectInZone: true, // 设为 true 时在 Angular zone 内建立扩展连接
}),
],
});
从源码实现看,provideStoreDevtools 是一个返回 EnvironmentProviders 的函数,它一次性注册了整套 Devtools 基础设施:provide-store-devtools.ts 中注册了 DevtoolsExtension、DevtoolsDispatcher、StoreDevtools 三个服务,并通过注入器工厂 createConfig 把传入的配置对象解析为完整的 StoreDevtoolsConfig,同时把 StateObservable、ReducerManagerDispatcher 重定向到 Devtools 的实现上。这解释了为什么只需要一行 provider 就能让 Devtools 完整接管状态流监听。
关于扩展选项的更多说明可参考 Redux Devtools 官方文档(上述示例注释已给出核心要点)。
模块化应用(NgModule)如何接入
如果项目仍使用 @NgModule 架构,可改用 StoreDevtoolsModule.instrument,它的参数与 provideStoreDevtools 完全一致:
import { NgModule } from '@angular/core';
import { StoreDevtoolsModule } from '@ngrx/store-devtools';
import { environment } from '../environments/environment';
@NgModule({
imports: [
StoreDevtoolsModule.instrument({
maxAge: 25,
logOnly: environment.production,
}),
],
})
export class AppModule {}
源码中 instrument.ts 的 StoreDevtoolsModule.instrument 本质上是把同样的 options 委托给 provideStoreDevtools,因此两种写法的行为与配置项完全等价。
完整配置项详解
调用 provideStoreDevtools(或 StoreDevtoolsModule.instrument)时可以传入一个可选的配置对象,其中每个属性都是可选的。config.ts 中 createConfig 给出了完整的默认值集合,是理解各参数语义的第一手依据:
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
maxAge |
number | false |
false |
历史树中最多保存的 action 数,超过后移除最旧条目;false 表示无限 |
logOnly |
boolean |
false |
是否以仅日志模式连接扩展;true 时仅启用 pause/export/test 功能 |
autoPause |
boolean |
false |
扩展窗口未打开时暂停记录,对应用零影响 |
name |
string |
NgRx Store DevTools |
监视器页面上显示的实例名 |
monitor |
function |
无 | 要挂载的 monitor 函数配置 |
actionSanitizer |
function |
— | 接收 (action, id),返回清洗后的 action |
stateSanitizer |
function |
— | 接收 (state, index),返回清洗后的 state |
serialize |
boolean | SerializationOptions |
false |
控制发送到扩展前的序列化方式 |
actionsSafelist |
string[] |
— | 只显示匹配 action type 的 action(正则数组) |
actionsBlocklist |
string[] |
— | 隐藏匹配 action type 的 action(正则数组);指定 actionsSafelist 时忽略此值 |
predicate |
function |
— | 每个 action 发送前被调用,返回 true 才允许发送 |
actionCreators |
ActionCreator[] | Record<string, ActionCreator> |
— | 在扩展 dispatcher 中可手动 dispatch 的 action creator |
trace |
boolean | (() => string) |
false |
为每个 action 记录堆栈;也可以传入自定义堆栈获取函数 |
traceLimit |
number |
75 |
trace 为 true 时最多保存的堆栈帧数 |
connectInZone |
boolean |
false |
扩展连接是否在 Angular zone 内建立 |
features |
object |
全部启用 | 逐项开关扩展的功能按钮 |
需要特别说明的是,createConfig 在合并配置时还会做两件校验与改写(见 config.ts):
- 当
logOnly: true时,features会被强制收敛为{ pause: true, export: true, test: true },即仅保留暂停记录、导出历史、生成测试三项能力; - 当
maxAge不为false且小于 2 时会抛出Devtools 'maxAge' cannot be less than 2, got ...的运行时错误,这与ng add标志中"必须大于 1 或等于 0"的约束一致。
maxAge
number (>1) | false:历史树中最多允许存储的 action 数量,达到上限后最旧的 action 会被移除。它对性能至关重要——历史越短,扩展面板的渲染与序列化负担越小。默认值为 false(无限)。注意默认值来自源码 createConfig 中的 maxAge: false,而 ng add 命令自动生成的配置是 maxAge: 25,二者并不冲突:前者是库的兜底默认,后者是脚手架给开发者的推荐值。
logOnly
boolean:以 log-only 模式连接扩展。默认 false 会启用扩展的全部 [features](即上面表中 features 的全部开关)。开启 logOnly 后,扩展界面只记录日志,禁用时间旅行、跳过、重排等操作,适用于生产环境的只读式监控。
autoPause
boolean:扩展窗口未打开时暂停记录 action 与状态变化。默认 false。开启后 Devtools 对应用运行的影响降为零,因为数据转发在窗口关闭时完全停止。
trace 与 traceLimit
trace 设为 true 时,会对每个 dispatch 的 action 记录 JavaScript 堆栈,你可以在扩展的 Trace 标签页中看到堆栈并直接跳转到触发该 action 的代码位置。它也可以是函数 () => string,用于返回自定义的堆栈字符串。traceLimit 是 trace 为 true 时最多保存的堆栈帧数,默认 75。由于堆栈采集本身有开销,建议仅在需要定位 action 来源时开启。
connectInZone
boolean:决定扩展连接是否在 Angular zone 内建立。默认 false。
源码实现揭示了它的真正作用:
- 在 extension.ts 的
createChangesObservable中,当connectInZone为false时,connect()会被包裹在ngZone.runOutsideAngular()中执行,因为connect通过window.postMessage注册message事件监听与扩展通信,若在 zone 内执行会导致不必要的变更检测循环; - 在 devtools.ts 中,
emitInZone算子则确保最终触发 reducer 与变更检测的归约操作回到 zone 内执行(ngZone.run),避免时序问题。
简单来说:连接建立放在 zone 外以避免无谓的变更检测,状态归约与通知回到 zone 内以保证 Angular 的响应性,二者缺一不可。
name
string:监视器页面上显示的实例名,便于在多个实例(例如微前端)中区分。默认值为 NgRx Store DevTools(见 config.ts 中的 DEFAULT_NAME)。
monitor
function:需要挂载的 monitor 函数配置。默认情况下使用 noMonitor。IS_EXTENSION_OR_MONITOR_PRESENT 令牌的工厂逻辑(provide-store-devtools.ts)会据此判断当前是否存在扩展或自定义 monitor,从而决定是否启用记录管线。
actionSanitizer 与 stateSanitizer
actionSanitizer(action, id):接收 action 对象与 id 数字,返回清洗后的 action;stateSanitizer(state, index):接收 state 对象与索引,返回清洗后的 state。
它们常用于在把数据发送到扩展前剔除敏感字段或不可序列化的内容。从 utils.ts 的实现看,这两个函数会在发送路径上被统一应用:发送单条 action 时只清洗当前 action/state;发送完整 lifted state 时则通过 sanitizeActions / sanitizeStates 清洗整个历史。值得注意的是,extension.ts 的 getExtensionConfig 注释明确说明 sanitizer 不会透传给扩展,而是由 @ngrx/store-devtools 自己先清洗再发送,以保证在"增量发送"与"全量发送"两种路径上行为一致。
serialize
控制数据序列化方式,取值如下:
undefined:使用常规JSON.stringify发送数据;false:同时处理循环引用;true:额外处理 date、regex、undefined、primitives、error 对象、symbol、map、set 与 function;- 对象:可包含
date、regex、undefined、NaN、infinity、Error、Symbol、Map、Set、function键,每个键设为true表示该类型需要被处理;function键还可以传自定义序列化函数。
如果你在状态树中存放了 Date、Map、Set 或 Error 等非常规值,建议显式设置 serialize: true,否则扩展面板中这些值可能无法正确显示。
actionsSafelist / actionsBlocklist
均为正则字符串数组,用于控制哪些 action type 在监视器中显示或隐藏:
actionsSafelist:仅显示匹配的 action;actionsBlocklist:隐藏匹配的 action;- 当两者同时指定时,
actionsSafelist优先,actionsBlocklist被忽略(见 config.ts 的注释)。
底层实现位于 utils.ts 的 isActionFiltered:数组元素会被 escapeRegExp 转义后拼接成正则与 action.type 匹配。例如 actionsBlocklist: ['@ngrx/router-store/*'] 可隐藏所有路由 action,减少调试噪音。此外,在时间旅行等全量更新场景下,filterLiftedState 会把过滤结果同步应用到整个 lifted state(stageActionIds、actionsById、computedStates),保证扩展面板与过滤规则完全一致。
predicate
(state, action) => boolean:每个 action 在发送前都会被调用一次,返回 true 才允许把当前数据发送给监视器。典型用法是按条件过滤——例如只在特定模块加载后记录、或按业务规则丢弃无关 action。它与 actionsSafelist / actionsBlocklist 配合时,任一条件命中都会过滤(见 utils.ts 中三个条件的 OR 关系)。
actionCreators
数组或对象形式的 action creator,注册后可在扩展的 dispatcher 中手动 dispatch 对应 action:
const bookRented = createAction(
'[Books] Rent',
props<{ id: number }>()
);
const bookReturned = createAction(
'[Books] Return',
props<{ id: number }>()
);
provideStoreDevtools({
// 在 dispatcher 中显示为 '[Books] Rent' 与 '[Books] Return'
actionCreators: [bookRented, bookReturned],
});
provideStoreDevtools({
// 在 dispatcher 中显示为 'rentBook' 与 'returnBook'
actionCreators: { rentBook: bookRented, returnBook: bookReturned },
});
- 传数组时,creator 按其 action type 名列出;
- 传对象时(例如用
createActionGroup创建的 action group),按对象的键名列出。
其底层原理在 extension.ts 中非常有意思:getActionCreatorDescriptors 会通过解析 creator 的源码字符串(正则匹配函数形参)提取参数名列表,生成 { name, func, args } 描述符传给扩展;当你在扩展 dispatcher 中输入参数并点击 dispatch 时,扩展回传 { selected, args } 载荷,unwrapAction 会先用间接 eval 把参数字符串求值成实际值,再调用 descriptor.func(...args) 生成 action 并注入 Store。这意味着你可以直接在扩展面板里填写参数、实时触发业务 action,非常适合联调。
features
配置对象,逐项开关扩展中的功能按钮,配置会被原样透传给浏览器扩展:
features: {
pause: true, // 开始/暂停记录 dispatch 的 action
lock: true, // 锁定/解锁 dispatch action 与副作用
persist: true, // 页面刷新时持久化状态
export: true, // 导出 action 历史到文件
import: 'custom', // 从文件导入 action 历史
jump: true, // 时间旅行(前后跳转)
skip: true, // 跳过(取消)action
reorder: true, // 在历史列表中拖拽排序 action
dispatch: true, // dispatch 自定义 action 或 action creator
test: true, // 为选中的 action 生成测试
}
默认全部启用。源码中 createConfig 注释特别提到要"显式列出所有 features",这是为了防止 lock 等选项在部分扩展版本中因未显式传入而不显示。与 logOnly 的联动关系(见上文)也在这里生效。
一个完整的配置示例
下面是官方文档给出的、可直接放入 app.config.ts 的完整示例:
export const appConfig: ApplicationConfig = {
providers: [
provideStoreDevtools({
maxAge: 25,
logOnly: false,
autoPause: true,
features: {
pause: false,
lock: true,
persist: true,
},
}),
],
};
该示例同时演示了:限制历史长度、开启全部扩展功能、自动暂停,以及按需关闭某个功能(这里关掉了 pause)。更多 options 与解释可参考 Redux Devtools 的扩展参数文档。
在生产环境排除 Store Devtools
Store Devtools 只为开发调试服务,应确保它不被打进生产 bundle。官方推荐的做法是把 provideStoreDevtools 放进会被 environment.prod.ts 替换的 environment.ts 中。
第 1 步:把 Devtools 放入 environment.ts
若项目还没有环境文件,可先执行 ng generate environments 创建。然后在 environments/environment.ts 中:
import { provideStoreDevtools } from '@ngrx/store-devtools';
export const environment = {
production: false,
providers: [provideStoreDevtools({ maxAge: 25 })],
};
生产环境对应的 environments/environment.prod.ts 则不包含 providers 数组(或为空数组),从而在 Angular 的文件替换机制下,生产构建不会引入 Devtools 的任何代码。
第 2 步:在 app.config.ts 中引用环境文件
import { environment } from '../environments/environment';
export const appConfig: ApplicationConfig = {
providers: [provideStore(), environment.providers],
};
这样配置后,开发环境通过 environment.providers 启用 Devtools,生产环境由于 environment.prod.ts 没有该字段,Devtools 不会被实例化,也不会进入生产 bundle。
若项目使用
@NgModule架构,可把同样的environment.providers展开进模块的 providers,或直接条件式调用StoreDevtoolsModule.instrument(...)。
与 Redux Devtools 扩展的协作原理
整个运行链路可归纳为:应用 dispatch action → DevtoolsDispatcher 转发 → StoreDevtools 用提升 reducer 推进 lifted state 并记录历史 → DevtoolsExtension.notify 增量或全量发送给浏览器扩展 → 扩展面板呈现时间旅行等操作;用户在扩展中触发的 jump/skip/import 等操作又通过 DISPATCH 类型的消息回到 liftedActions$ 流,重新进入 Store 归约。
在 extension.ts 中可以看到几个关键实现细节:
- 扩展连接通过
window.postMessage建立,消息类型区分START、DISPATCH、STOP、ACTION; notify对普通PERFORM_ACTION走"增量发送"(只发当前 action + state),对时间旅行、状态导入、模块初始化等事件走"全量发送"(序列化整个 lifted state),以在性能与完整性之间取得平衡;- 状态导入(
IMPORT_STATE)会等待最多 1 秒内不再出现UPDATE事件,以确保懒加载的 reducer 都已就绪,再应用导入的状态(见createActionStreams中的timeout(1000)+debounceTime(1000)); - 当扩展未安装时(
window.__REDUX_DEVTOOLS_EXTENSION__不存在),provide-store-devtools.ts 中的createReduxDevtoolsExtension返回null,DevtoolsExtension的动作流退化为EMPTY,应用本身照常运行,不受任何影响。
另外,StoreDevtools 实现了 OnDestroy 并在销毁时取消两个内部订阅,避免微前端场景中反复创建/销毁应用导致的内存泄漏。
相关资源
- 官方配置文档:store-devtools/config.md
- 安装说明:store-devtools/install.md
- 生产排除指南:store-devtools/recipes/exclude.md
- 核心配置与默认值:modules/store-devtools/src/config.ts
- Provider 注册:modules/store-devtools/src/provide-store-devtools.ts
- 历史树与时间旅行实现:modules/store-devtools/src/devtools.ts
- 扩展通信实现:modules/store-devtools/src/extension.ts
- 过滤与清洗工具:modules/store-devtools/src/utils.ts
- 模块化接入:modules/store-devtools/src/instrument.ts