Pinia 3 状态分层:按变更原因切,不按页面切
这一节承诺的五件事
- 能对一份现有的 stores 目录做一次拆分审计,指出哪些该合并、哪些该上移到 service 层、哪些不该是全局 store
- 能写出"外部改不到 state"的 setup store,并说清它与 options store 在
$reset()上的差异 - 能识别循环依赖的三种成因,并判断该修引用时机还是该改拆分
- 能为一组状态选出持久化介质,并说明为什么不选另一种
- 能给异步 action 加上竞态保护,解释
finally里那道判断为什么不能省
版本基线:Pinia 3.0.0 于 2025-02-11 发布,3.x 最后一个是 3.0.4(2025-11-05);4.0.0 是 2026-07-14,最新 4.1.0 是 2026-10-14。本文以 3.0.4 为基线,defineStore 的 setup 写法在 4.x 上同样成立,涉及版本差异会单独标注。
1. 先看清两代的分界线
从依赖变化能读出很多东西。这张表最好横着看最后一列:
| 版本 | vue peer | @vue/devtools-api | 关键变化 |
|---|---|---|---|
| 2.3.1 | ^2.7.0 || ^3.5.11 | 内置依赖 ^6.6.3 | 依赖 vue-demi 兼容 Vue 2 |
| 3.0.0 | ^2.7.0 || ^3.5.11 | 内置依赖 ^7.7.1 | 去掉 vue-demi,体积变小 |
| 3.0.4 | ^3.5.11 | 内置依赖 ^7.7.7 | 彻底放弃 Vue 2 |
| 4.1.0 | ^3.5.11 | peer 依赖 ^8.2.1 | devtools API 变成需要显式安装 |
最后一行那一格值得停一下。4.x 把 @vue/devtools-api 从内置依赖改成 peer 依赖,TypeScript 下限也抬到 >=5.6.0。这意味着升到 4.x 之后如果没显式安装 devtools API,构建可能只给一个警告,但调试面板会静默失效。
这类"不报错的功能缺失"比编译失败难查得多。它不会让你在下午三点发现,会让你在两周后排查一个状态问题时发现。
这个类目的位置关系是这样的——状态管理不是孤立的一层,它同时被路由、组件、持久化三面拉扯:
虚线那一条是这一节要反复强调的边界。Store 只管状态,不该管流程。
2. 导入案例:三个页面,三份订单
2026 年 8 月接手一个采购系统,stores/ 目录下有这么一组文件:useOrderListStore、useOrderDetailStore、useOrderEditStore。
同一个订单,在列表页改了一次备注,进详情页看到的还是旧备注。原因是详情 store 在 onMounted 里自己又拉了一遍,拉回来的是缓存前的版本。三份数据、三处同步、三次请求。
团队当时的修法是加 watch:详情 store 监听列表 store 的 list,编辑 store 监听详情 store 的 current。四个文件互相监听之后,一个保存动作触发了六次请求。
停下来问一句:这三份状态,它们的变更原因是同一个吗?是。它们都是"订单数据被后端更新了"。既然是同一个原因,就应该待在一个 store 里。
3. 拆分的判断信号
正确的依据不是"页面长什么样",是变更原因是否一致。同一个 store 里的状态,应该因为它们总是被同一类操作一起改变而聚在一起。
三个可以直接对照的信号:
信号一,两个 store 需要互相 watch 对方来保持一致。说明它们本来是同一个东西,该合并;如果合并后太大,该抽出第三个共享 store。
信号二,一个 store 的 action 里连续调用三个其他 store 的 action。说明它承担了编排职责,应该上移到 service 层或页面级 composable。Store 编排别的 store,等于把业务流程藏进了状态层,测试时你没法单独验证流程。
信号三,一个 store 只被一个组件使用,且生命周期与该组件完全重合。那它不该是全局 store,用 provide/inject 或组件内状态更合适。
反过来,跨路由存活是保留全局 store 最硬的理由:登录态、权限码表、用户偏好、购物车。只有这些"路由切了也不能丢"的数据,才值得进 Pinia。
反例:按页面拆。OrderList 和 OrderDetail 各建一个 store,看起来职责清晰,实际上把一份后端数据变成了两份客户端副本,同步逻辑会无限长出来。
4. 动手任务:把修改入口收窄
任务目标:写出一个外部无法直接改 state 的 store,并验证 $reset() 的行为差异。
setup store 相比 options 写法最大的好处不是语法糖,而是你可以选择不把 state 的 ref 返回出去。Pinia 不对 state 做写保护——store.list = [] 这种直接赋值在任何 store 上都合法,devtools 最多给个警告。所以"谁能改状态"只能靠返回什么来控制。
// src/stores/order.ts
// 前提:pinia@3.0.4+,TypeScript 5.x
import { computed, ref } from 'vue'
import { defineStore } from 'pinia'
import { fetchOrders, type Order } from '@/api/order'
export const useOrderStore = defineStore('order', () => {
// 内部可变状态:不返回 ref 本体,外部就改不到
const list = ref<Order[]>([])
const loading = ref(false)
const keyword = ref('')
// 对外只给只读视图:computed 没有 setter,赋值直接报类型错误
const orders = computed(() => list.value)
const total = computed(() => list.value.length)
const isLoading = computed(() => loading.value)
async function load() {
loading.value = true
try {
list.value = await fetchOrders()
} finally {
loading.value = false
}
}
function setKeyword(v: string) { keyword.value = v } // 唯一修改入口
return { orders, total, isLoading, load, setKeyword }
})预期输出:在组件里写 store.orders = [],TypeScript 立刻报 Cannot assign to 'orders' because it is a read-only property。而如果你图省事把 list 一起 return 出去,写 store.list = [] 就能编译通过——"收窄入口"从此只是口头约定。
第二件事,验证 $reset():setup store 没有内置的 $reset()。options store 调它会恢复初始 state,setup store 上它不会被实现——开发环境只打印一行错误提示,生产环境静默无效。
预期输出:开发环境下 console 出现一条提示、state 不变;生产构建里连提示都没有。这就是我建议在"退出登录要清空全部 store"的项目里,统一给每个 store 补一个 reset() action 的原因。
第三件事,从 store 里解构状态会丢响应性,必须用 storeToRefs。但按上面的写法只暴露了 computed,storeToRefs 拿到的是只读引用,可以直接用;action 本身是函数,可以放心解构。
这里容易卡住的地方:模板里"数据不更新"的现象,八成是解构丢了响应性,但它不会报任何错,你会一路查到接口层。
5. 循环依赖:三种成因,三种修法
Store 之间互相引用是必然的——订单要读用户信息,用户要读最近订单。问题出在引用的时机。
两条路径只差一行代码的位置,结果完全不同:模块顶层 import 并立即调用会形成静态循环,打包器无法保证初始化顺序;把调用推迟到 action 内部,循环就变成运行时按需解析。
规则可以写死三条。可以在顶层 import useXxxStore(类型和引用需要它),但不要在模块顶层执行 useXxxStore() 拿到实例;必须在 action、getter 或组件 setup 里调用;如果两个 store 真需要共享同一份状态而不是互相读,说明拆分错了。
还有一种更隐蔽的成因:storeToRefs 在模块顶层被调用。它内部会触发 store 实例化,效果和顶层调用一样,同样把循环依赖变成运行时的 undefined。
6. 持久化:先定介质,再定字段
持久化最容易被当成"加个插件就完事"。实际决策点在介质,选错介质后面全是补丁。
| 介质 | 容量 | 生命周期 | SSR 可见 | 适用 |
|---|---|---|---|---|
localStorage | 约 5MB | 永久,需手动清 | ❌ 服务端没有 | 用户偏好、主题、草稿 |
sessionStorage | 约 5MB | 标签页关闭即失效 | ❌ | 单次流程的临时态 |
| Cookie | 约 4KB | 可设过期时间 | ✅ 随请求发送 | 会话标识、租户 ID |
| IndexedDB | 按配额,通常数百 MB | 永久 | ❌ | 离线缓存、大列表快照 |
pinia-plugin-persistedstate 4.7.1(2025-11-01)是这条线上最常用的方案,peer 要求 pinia >= 3.0.0,3.x / 4.x 都兼容。它的关键选项是 pick / omit——默认会把整个 state 序列化进去。
存一个订单列表进去,几天后用户 localStorage 就满了,而写满时抛的 QuotaExceededError 会被静默吞掉(除非开 debug)。这条我建议写进代码评审清单,因为它只在用户机器上出现。
// src/stores/preference.ts —— 只持久化该持久化的字段
// 前提:pinia@3.0.4+、pinia-plugin-persistedstate@4.7.1
export const usePreferenceStore = defineStore(
'preference',
() => {
const theme = ref<'light' | 'dark'>('light')
const sidebarCollapsed = ref(false)
const recentSearches = ref<string[]>([])
return { theme, sidebarCollapsed, recentSearches }
},
{
persist: {
key: 'preference',
// 白名单优于黑名单:新增字段默认不会被意外写盘
pick: ['theme', 'sidebarCollapsed'],
},
},
)预期输出:Devtools 的 Application 面板里出现 app:preference 键,内容只含 theme 与 sidebarCollapsed,recentSearches 不在其中——这正是白名单的价值,将来新增一个字段时默认不会被写进去。
还有一件必须提前设计的事:结构变更。给 key 加版本号(如 app:v2:preference)比写迁移函数便宜得多;确实要迁移就用 beforeHydrate 读旧键、afterHydrate 删旧键,别在 store 初始化里写判空分支——那段代码每次启动都会跑一遍。
这里有一条我明确不建议的做法:不建议用 omit 黑名单。它的失效方式是"团队新加了一个字段,没人记得去黑名单里补一行",等发现问题时用户机器上已经存了几百 KB 不该存的东西,而且你还得写清理逻辑。
7. 只在生产暴露的两件事
水合顺序。SSR 下服务端和客户端各自 createPinia(),两边必须共享同一份初始 state,否则水合瞬间会出现"服务端渲染的是登录态、客户端首帧是未登录"的闪烁。官方做法是把服务端 pinia.state.value 序列化进 HTML,客户端在 app.use(pinia) 之前赋回去。
顺序错了不会报错,只会闪一下。这类问题永远在弱网真机上才被发现。
还有个高频坑:在 store 的模块顶层访问 localStorage。Node 环境没有这个对象,SSR 构建直接抛 ReferenceError,而本地 vite dev(纯客户端)完全正常。所有浏览器 API 的访问都要放进 action 或 onMounted,或者在 store 里判断 typeof window !== 'undefined'。
异步竞态。搜索框输入、筛选切换、路由参数变化,都会让同一个 action 并发执行。后发的请求先返回、先发的后返回,最终 state 被旧数据覆盖。这类 bug 本地几乎复现不了,弱网下必现。
// src/stores/order.ts —— 在 useOrderStore 内部追加竞态控制
// 前提:pinia@3.0.4+,浏览器需支持 AbortController
export const useOrderStore = defineStore('order', () => {
const list = ref<Order[]>([])
const loading = ref(false)
// 序号与 controller 挂在 store 闭包里,天然是"每个实例一份"
let seq = 0
let controller: AbortController | null = null
async function search(keyword: string) {
const current = ++seq
controller?.abort()
controller = new AbortController()
loading.value = true
try {
const res = await searchOrders(keyword, { signal: controller.signal })
if (current !== seq) return // 双保险:没被 abort 也丢弃过期结果
list.value = res
} catch (e) {
if ((e as Error).name === 'AbortError') return // 主动取消不算错误
throw e
} finally {
if (current === seq) loading.value = false // 只有最新一次能关 loading
}
}
return { list, loading, search }
})预期输出:在搜索框快速输入 abc 三次,Network 面板里前两个请求状态显示 canceled,列表最终显示 abc 的结果,loading 在最后一次返回后关闭。
两个细节不能省。finally 里那句 if (current === seq) 省掉之后,先发请求的 finally 会把最新请求的 loading 关掉,界面提前结束加载态;AbortError 不单独判断,用户每敲一个字符就触发一次错误上报。
至于哪个请求该取消,标准是用户是否还关心结果。搜索建议、列表筛选该取消;提交订单、支付回调不该取消——后者的取消只会让状态更混乱,宁可让请求跑完再丢弃结果。
8. 三处容易想反的地方
很多人以为 setup store 只是 setup() 语法糖,实际上它把"哪些东西对外可见"变成了一个显式的设计决定。options store 的 state 天然全量暴露,setup store 可以只暴露 computed。
很多人以为 storeToRefs 只是防止丢响应性的工具函数,实际上它在模块顶层被调用会触发实例化,是循环依赖的一种隐蔽成因。
很多人以为 Devtools 能看到所有 state 变更,实际上它只能看到 action 触发的变更。在组件里写 store.list.push(...),devtools 里会显示成一次来源不明的 mutation。所以第 4 节的"收窄入口"不只是代码整洁问题,也是可调试性问题。
9. 三问,答完再动手
第一题。你的项目里有 useUserStore 和 usePermissionStore,后者依赖前者的角色字段计算结果。应该合并还是保留两个?判断依据是什么?
第二题。一个 store 的 reset() 你写在 action 里,但它内部调用了 localStorage.removeItem。这个 store 要支持 SSR,你打算怎么改?
第三题。给上面的 search 加一个"最小输入长度 2 才发请求"的约束。这个约束该写在 store 里还是组件里?两种做法的测试成本差在哪?
10. 术语对照
| 中文 | 英文 | 一句话解释 |
|---|---|---|
| 状态仓库 | store | 承载跨组件、跨路由共享状态与修改动作的容器 |
| 组合式仓库 | setup store | 用 setup() 函数形式定义的 store,可选择性暴露内容 |
| 引用解包 | storeToRefs | 把 store 中的状态转成独立 ref,保留响应性的解构手段 |
| 竞态 | race condition | 并发请求返回顺序与发起顺序不一致导致的状态覆盖 |
| 水合 | hydration | 客户端接管服务端直出的 HTML 并恢复状态的过程 |
| 白名单持久化 | pick | 只持久化列出的字段,新增字段默认不写盘 |
| 变更原因 | reason to change | 一组状态是否该放在一起的判断依据 |
参照官方 Pinia 文档的 SSR 一节 与 核心概念 对照阅读,能看到同一套 API 在服务端与客户端下的差异;持久化插件的选项以 pinia-plugin-persistedstate 文档 为准。本文的取舍判断部分属于工程经验,截至 2026 年 11 月的版本成立,升级到 4.x 后 devtools 相关结论需要按实际依赖重新核对。