Pinia 的 $patch 是批量更新 state 的安全高效方法,支持对象式(一次性设多个值)和函数式(基于当前值计算更新)两种用法,避免多次响应触发与丢失响应式,推荐在 action 中封装使用。

Pinia 的 $patch 是专门用于批量更新 store 中多个 state 属性的便捷方法,它比逐个赋值更简洁、更语义化,也比直接替换整个 state 更安全(保留未修改的字段)。
用对象方式一次性修改多个属性
最常用的方式是传入一个普通对象,键名对应 state 中的属性名,值为新值:
store.$patch({
count: 10,
name: 'Alice',
isActive: true
})
这会同时更新 count、name 和 isActive 三个字段,其余 state 字段保持不变。
用函数方式实现基于旧值的计算更新
当新值依赖当前 state 时,传入一个函数,参数是当前 state 的只读副本(不能直接修改):
store.$patch((state) => {
state.count += 5
state.lastUpdated = Date.now()
})
注意:函数内可直接赋值给 state.xxx,Pinia 会自动收集变更并触发响应式更新。这种方式适合需要读取当前值再计算的场景,比如递增、时间戳更新等。
和直接赋值、$state 替换的区别
-
对比逐个赋值:写
store.count = 10; store.name = 'Alice'会触发多次响应式更新,而$patch合并为一次,性能更好、调试更清晰; -
对比
store.$state = {...}:后者会完全替换整个 state 对象,丢失响应式连接(除非用reactive重新包装),而$patch是“合并式更新”,安全可靠; -
不可用于嵌套深层属性的局部更新:比如
user.profile.age,$patch不支持点号路径(那是 Vue 2 的写法),需用函数方式手动访问嵌套对象。
配合 action 封装批量逻辑更清晰
推荐在 store 的 action 中使用 $patch,把业务含义显性化:
actions: {
resetUser() {
this.$patch({
count: 0,
name: '',
isActive: false,
lastUpdated: null
})
},
updateUserInfo({ name, email }) {
this.$patch({
name,
email,
lastUpdated: Date.now()
})
}
}
这样调用时语义明确:store.resetUser() 或 store.updateUserInfo({ name: 'Bob', email: 'b@x.com' })。


















