Pinia 的 $patch 方法是批量更新 store state 的推荐方式,支持对象式(同步原子更新)和函数式(基于旧值计算)两种用法,区别于 $reset(重置初始值)和 $hydrate(SSR 恢复)。

Pinia 的 $patch 方法是批量更新 store 中多个 state 字段的推荐方式,比逐个赋值更简洁、响应式更可靠,也支持事务式更新逻辑。
用对象形式一次更新多个字段
最常用的方式是传入一个普通对象,键名对应 state 中的属性名,值为新值:
store.$patch({
username: 'alice',
age: 28,
isActive: true
})
这种方式会同步触发所有被修改字段的响应式更新,并且整个操作是原子性的(即 Vue 的依赖追踪只触发一次更新)。
用函数形式实现基于旧值的计算更新
当新值依赖当前 state 值时(比如递增计数器、拼接数组),应使用函数形式,参数是当前 state 的只读副本:
store.$patch((state) => {
state.count += 1
state.items.push('new-item')
state.lastUpdated = Date.now()
})
注意:函数内直接修改 state 对象属性即可,不需要返回新对象;Pinia 会自动识别变更并更新响应式系统。
配合 $state 实现“全量替换”(慎用)
虽然不推荐日常使用,但你也可以用 $patch 替换整个 $state(等价于 store.$state = {...}):
store.$patch({
username: 'bob',
age: 30,
// ...其他所有字段必须显式写出,缺失字段会被设为 undefined
})
⚠️ 风险提示:这种方式会丢失未列出的 state 字段,除非你确保对象包含全部 state 属性。一般只在初始化或重置场景下考虑。
与 $reset 和 $hydrate 的区别
$patch 是局部、增量更新;$reset() 是还原到初始 state;$hydrate() 是服务端渲染时恢复状态。三者用途不同,不要混淆。
如果只是改几个字段,优先选 $patch({ ... });需要逻辑计算再更新,就用 $patch(fn)。


















