$onAction 是 Pinia 提供的 AOP 式 action 监听机制,支持 before、after、onError 三阶段钩子,仅监听 actions 方法,不监听 $patch 等 state 操作;可用于日志、loading、耗时统计等场景。

$onAction 是 Pinia 提供的面向切面(AOP)式监听机制,专用于捕获 store 中所有 actions 方法 的执行全过程——包括开始前、成功后、出错时三个关键节点。它不监听 $patch、$reset 等直接操作 state 的行为,只作用于定义在 actions 里的函数。
基本用法:监听单个 store 的 action
每个 store 实例都自带 $onAction 方法,调用后传入一个回调函数即可订阅其所有 actions:
- 回调接收一个上下文对象,含
name(action 名)、args(参数数组)、store(当前 store 实例) -
after钩子在 action 执行完成(包括 await Promise resolve)后触发,可拿到返回值 -
onError钩子能同时捕获同步throw和异步reject,无需在 action 内写 try/catch
示例:
const store = useUserStore()
store.$onAction(({ name, args, after, onError }) => {
console.log(`【开始】${name}`, args)
after(result => console.log(`【完成】${name}`, result))
onError(error => console.warn(`【失败】${name}`, error))
})
全局拦截:用插件统一监控所有 store
在创建 pinia 实例后,通过 pinia.use() 注册插件,即可为每个新初始化的 store 自动添加 $onAction 监听:
- 插件函数接收
{ store }对象,内部调用store.$onAction即可 - 适合统一实现日志、耗时统计、loading 状态联动、错误上报等跨 store 场景
示例(记录所有 action 耗时):
${store.$id}.${hook.name} 耗时 ${Date.now() - start}ms
常见实用场景
统一 loading 状态管理:
在 before 阶段设 store.loading = true,在 after 或 onError 中设为 false,组件中直接绑定 v-loading="store.loading" 即可响应任意 action。
参数预处理与校验:args 是引用传递,可在 before 回调中安全修改,例如过滤敏感字段、注入用户 token 或时间戳。
按需过滤或分级处理:
用 name.startsWith('fetch') 匹配接口类 action,或用 ['login', 'delete'].includes(name) 精准识别高危操作,再决定是否打详细日志、触发 Sentry 上报或跳转错误页。
注意事项
监听默认绑定到当前组件生命周期:在 setup() 中调用 $onAction,组件卸载时会自动清理;如需长期存在(如埋点 SDK),可传入 { detached: true } 并自行保管返回的取消函数。
不能直接“取消” action 执行,但可通过 throw new Error() 中断流程(需配合 onError 做兜底),或静默忽略不满足条件的调用(如权限不足时不抛错也不执行后续逻辑)。











