尧图网站开发 
1. 为什么 Pinia 会成为 Vue3 项目的默认选择在 Vue3 Vite 项目里数据流一旦过了“父子组件互传”这个阶段几乎每个人都会遇到同一种尴尬props像瀑布一样往下漏$emit像接力棒一样往回传中间再掺和几个provide/inject、ref、computed代码很快就变成一团乱麻。这时候把共享状态抽离出来交给一层独立仓库统一维护是最直接也最成熟的解法。到了 Vue3 时代这个解决方案已经有了明确答案Pinia。它不是 Vuex 换个马甲而是从 API 设计、类型推导、模块组织到开发体验都为“组合式 API”重新设计的一套状态管理架构。Pinia 设计里最有意思的一点是打破了 Vuex 时代“全局一个仓库、按模块切片”的固定套路。Pinia 天生是多仓库的每个 store 都是一个独立的useXxxStore()函数组件里想用哪个就调用哪个。这带来的架构收益非常实在可以按业务域收敛状态拿到某个模块的代码视觉范围内就能看到这块业务的数据、变更方法、异步请求全在一起不需要在store/modules/a、store/actions/b、store/getters/c之间来回跳。这一条直接改变了多人协作时的心智负担也是我后来在新项目里彻底放弃 Vuex 的最大原因。这篇文章按“架构”的角度来讲不会逐行翻译文档而是讲清楚三件事Pinia 的设计逻辑是什么、在 Vite 工程里怎么组织多 store 才不乱、以及上了生产环境之后会遇到哪些文档里不写的坑。适合正在做后台管理系统、中台项目或者任何需要长期迭代的 Vue3 项目的前端开发者参考。1.1 对比 Vuex不是改版是推倒重来很多从 Vue2 过来的同学第一反应是拿 Pinia 和 Vuex 做等价对比。实际上两者的差距不能只靠“新增了 setup store”来概括我整理了这几个关键维度对比项Vuex 4Piniastore 形态单一 store modules 嵌套多 store 平铺每个 store 独立修改状态commit mutation同步限制严格直接改 state或调用 action无严格约束异步处理action 中可异步仍需 commitaction 本身就是普通函数随意 awaitTypeScript 推导需要大量手写类型与辅助函数store 创建即获得完整类型推导嵌套模块支持 modules 嵌套复杂度高不支持嵌套但可以互相调用结构更扁平插件生态官方插件较少写法笨重持久化等插件轻量易配最关键的是 Mutation 没了。Vuex 当年引入 Mutation是为了配合 DevTools 做时间旅行调试但在简化心智和类型推导面前这件事的收益越来越低。Pinia 直接告诉开发者想改状态就改想写异步就写DevTools 依然能记录每一次变更。这非常符合“组合式 API”的哲学把复杂机制留给框架把简单留给业务代码。1.2 底层原理reactive 与 computed 撑起整座仓库Pinia 说到底是 Vue3 响应式 API 的一层封装。一个 store 的state本质上是reactive(obj)getters是computed的集合actions就是普通函数。理解这一点很多使用时的“直觉”就有了依据为什么直接修改store.count是可以的因为store对象本身是被reactive处理的属性访问会被响应式系统捕获界面自然更新。为什么解构store里的 state 会丢失响应式因为reactive对属性拦截的效果依赖对象引用你把原始值拿出去就脱离了代理对象。为什么$patch能批量更新因为$patch内部会对整个变更对象做一次合并再一次性触发依赖更新比连续多次赋值性能更好也更利于 DevTools 记录为单次变更。源码层面Pinia 在创建 store 时会给每个仓库生成一个唯一id并把 state、getters、actions 挂到一个通过reactive构建的上下文中。所谓 action 里的this指向的就是这个上下文的代理对象。所以你在 action 里写this.count 2和写store.count 2最终执行路径几乎一样。理解这层机制后你会自然明白为什么 setup store 里用ref声明状态也行用reactive声明状态也行因为他们最后都会转换成响应式数据。1.3 两种 store 写法Option Store 与 Setup Store 怎么选Pinia 提供两套定义 API这是初学者最容易纠结的点。我把这两者的取舍说透Option Store用state/getters/actions三个字段定义结构最接近 Vuex写起来规整。优点是代码一眼能认出哪些是数据、哪些是计算属性、哪些是行为适合团队里新人多、希望约定强的场景。Setup Store写法和组件里的setup()几乎一样用ref/reactive/computed声明状态用普通函数定义方法。优点是可以自由使用watch、computed、自定义组合式函数逻辑复用更方便。我的建议是老项目迁移或团队规范强调可读性时用 Option Store新项目、业务逻辑重的场景用 Setup Store。实际上大型项目里两种混用也完全没问题Pinia 不限制。真正要注意的是风格统一别一个模块一种写法会让后来维护的人拿着代码无所适从。2. 工程化落地在 Vite 项目里初始化 Pinia光看理念没用得落到代码里。这一节从零开始讲 Vite 项目里怎么接入 Pinia、目录怎么摆、第一个 store 怎么写才规范。2.1 安装与入口配置Vite 创建的项目默认没有 Pinia安装只需要一条命令npm install pinia # 或者 pnpm add pinia安装完成后修改项目的入口文件main.ts或main.js把 Pinia 挂到应用实例上import { createApp } from vue import { createPinia } from pinia import App from ./App.vue const app createApp(App) const pinia createPinia() app.use(pinia) app.mount(#app)这里有一个容易被忽略的细节createPinia()生成的实例是一个 Vue 插件但它在内部会注册一个全局的provide把 pinia 实例注入到所有组件。所以组件里调用useStore()时不需要手动传 pinia 实例——只要你在app.use(pinia)之后通过组件渲染链访问它都能自动找到。但如果要在组件外使用 store比如路由守卫、工具函数就得手动把 pinia 实例传进去这个坑后面专门讲。2.2 目录结构多 store 的推荐组织方式Pinia 没有强制的目录规范我基于多个中后台项目的实践推荐这样组织src/ ├── stores/ │ ├── index.ts # 统一导出方便引用 │ ├── modules/ │ │ ├── user.ts # 用户信息、登录态 │ │ ├── app.ts # 侧边栏、主题、布局状态 │ │ ├── permission.ts # 权限、路由表 │ │ ├── tabs.ts # 多标签页导航 │ │ └── settings.ts # 系统设置 │ └── plugins/ │ └── persist.ts # 持久化插件封装这里的关键思路是按业务域而不是按数据类型来划分文件。比如不要搞state.ts、actions.ts这种按角色分的目录因为一个业务变更通常会同时改数据、方法和计算属性拆开反而增加查找成本。按模块拆分后每个文件内部再按state/getters/actions组织内容读起来才顺。2.3 第一个完整 store以用户登录态为例拿中后台最常见的用户模块来展示一个接近生产质量的 store// src/stores/modules/user.ts import { defineStore } from pinia import { loginApi, getUserInfoApi, logoutApi } from /api/auth import { storage } from /utils/storage export const useUserStore defineStore(user, { state: () ({ token: storage.get(token) || , userInfo: {} as UserInfo, roles: [] as string[], }), getters: { isLogin: (state) !!state.token, displayName: (state) state.userInfo?.nickname || state.userInfo?.username || 未登录, }, actions: { async login(payload: LoginParams) { const { token } await loginApi(payload) this.token token storage.set(token, token) }, async fetchUserInfo() { const data await getUserInfoApi() this.userInfo data.userInfo this.roles data.roles ?? [] }, async logout() { await logoutApi() this.reset() }, reset() { this.token this.userInfo {} this.roles [] storage.remove(token) }, }, })这个例子里有几个值得展开的点state 用函数返回初始值和组件 data 保持一致好处是每次创建 store 都能拿到新的初始状态测试和复用更安心。getters 里返回新对象或经过计算的值比如displayName汇总了多个字段组件里拿到它就不需要再写一遍if else。action 里直接访问thisOption Store 约束下的this就是 store 实例类型推导在编辑器中会直接提示不需要额外声明返回值类型。reset()方法做成 action可以一次性把所有状态恢复为初始值。登录过期、切换账号这类场景只要调用一次store.reset()不会遗漏任何字段。3. 模块化状态管理架构实操到了这一步多 store 之间如何协动、数据流怎么设计就是架构的核心了。这一节用真实后台系统的拆法做案例。3.1 典型后台系统的拆法一份可复用的模块对照表后台管理系统是 Pinia 最常见的应用场景。我一般按下面的方式拆模块模块名称负责的状态典型 actions典型 gettersusertoken、用户信息、角色login / fetchUserInfo / logoutisLogin、displayNamepermission路由表、按钮权限、菜单树generateRoutes / resetaccessibleRoutestabs多标签页列表、当前激活页addTab / removeTab / closeOtherscachedViewsapp侧边栏展开收起、设备类型、全局 loadingtoggleSidebar / setDevicesidebarOpenedsettings主题色、布局模式、语言、水印setTheme / setLayout / setLanguagethemeStyle这个划分有个核心原则每个模块只关心自己的一组内聚状态模块之间可以通过调用对方的方法协作但不直接修改对方 state。比如登录成功后user store 拿到了角色信息接下来要把角色同步给 permission store 去生成可访问路由。正确的做法是在 user 的 action 里调用 permission store 的 action或者由页面组件编排两者的调用顺序而不是 user 直接把 permission 的数据给写了。这样每一块状态都有唯一“责任人”排查问题时能迅速锁定。3.2 store 之间互相调用与依赖顺序一个 store 内部调用另一个 store在 Pinia 里非常自然直接useOtherStore()即可// src/stores/modules/permission.ts import { useUserStore } from ./user export const usePermissionStore defineStore(permission, { state: () ({ routes: [] as RouteRecordRaw[], }), actions: { async generateRoutes() { const userStore useUserStore() const roles userStore.roles // 根据角色过滤动态路由 const accessedRoutes filterAsyncRoutes(asyncRoutes, roles) this.routes accessedRoutes }, }, })注意这里有一个store 必须已被创建的时序问题在 script 顶层或组件setup()里调用usePermissionStore()时组件渲染链已经能提供 pinia 实例所以没问题。但如果是在 store 的state初始化函数里直接调用另一个 store就会报“getActivePinia was called with no active Pinia”的错。解决办法是不要在 state 初始化里调用其他 store应该放到 action 或 getter 里再取。getter 因为执行时机晚反而安全。3.3 Setup Store 高阶用法复用组合式函数前面提到 Setup Store 可以自由使用组合式函数这里给一段实际代码// src/stores/modules/device.ts import { ref } from vue import { useEventListener } from vueuse/core import { defineStore } from pinia export const useDeviceStore defineStore(device, () { const width ref(window.innerWidth) const isMobile ref(false) function update() { width.value window.innerWidth isMobile.value width.value 768 } useEventListener(window, resize, update) update() return { width, isMobile } })在这个文件里useEventListener会在 store 创建时自动注册监听销毁时自动清理。这要比在组件里写一堆addEventListener/removeEventListener干净得多。更重要的是width和isMobile天然是响应式的任何组件调用useDeviceStore()都能同步获得最新的窗口状态。3.4 数据流的职责边界store 与组件该各管什么状态管理架构最模糊的边界在于“哪些数据该进 store哪些留在组件里”。我的判断标准很简单多组件共享的数据进 store纯组件内部 UI 状态留在组件内。比如弹窗的visible、表单的临时输入值、列表的筛选条件这些通常不需要全局共享放进 store 只会徒增噪音。反过来登录态、权限列表、用户偏好、全局主题这类被多处依赖的状态放到 store 是合理的。另外注意store 不该被当成“万能请求层”。一份只服务于某个表格的数据直接在组件里的onMounted请求并存在ref中就好除非数据在多个不相关的组件里都要用或者需要缓存复用才放进 store。这个原则能帮整个项目保持轻盈避免 store 文件越来越大、越来越杂。4. 持久化、HMR 与生产环境进阶状态管理到了生产环境躲不开几个现实问题刷新页面后状态不能丢、开发时的热更新不能把 store 状态弄丢、敏感数据不能明文存在 localStorage。这一节讲透。4.1 持久化方案使用 pinia-plugin-persistedstate官方没有默认带上持久化能力社区最常用的是pinia-plugin-persistedstate。安装配置很简单npm install pinia-plugin-persistedstate// src/stores/index.ts import { createPinia } from pinia import piniaPluginPersistedstate from pinia-plugin-persistedstate const pinia createPinia() pinia.use(piniaPluginPersistedstate) export default pinia然后在具体 store 里开启export const useUserStore defineStore(user, { state: () ({ token: , userInfo: {} }), persist: { key: my-app-user, storage: sessionStorage, // 按需选择 localStorage / sessionStorage pick: [token, userInfo], // 只持久化指定字段 }, // ... })这里有三个经验之谈pick 字段时只保留真正需要“跨刷新”的数据。比如token和userInfo需要保留但临时的下拉列表数据没必要。考虑用sessionStorage而不是localStorage存敏感信息。localStorage会永久保留而用户关闭浏览器后sessionStorage自动清理安全边界更好。不要在 store 里直接存大体积数据比如完整的用户列表、文件 base64持久化插件会把它们序列化到浏览器存储里刷新一次就占一次内存性能和隐私都受影响。4.2 HMR 热更新开发时不丢 stateVite 的开发服务器天然支持热更新但 store 模块的热更新有讲究。Pinia 官方提供了一个模式在 store 文件底部加上import { acceptHMRUpdate, defineStore } from pinia if (import.meta.hot) { import.meta.hot.accept(acceptHMRUpdate(useUserStore, import.meta.hot)) }这段代码的作用是当user.ts文件被修改时让 Vite 只替换 user store 的定义而不是销毁整个应用再重新渲染。如果不加HMR 可能会重建所有 store导致你手动修改过的状态比如登录态在编辑器保存瞬间被清空调试成本立刻飙升。建议每个 store 文件都加上这段不要偷懒。4.3 组件外使用 store路由守卫与工具函数在路由守卫里判断登录态、在 axios 拦截器里读取 token都是很常见的需求。但这些代码不在组件渲染链里直接useUserStore()会找不到 pinia 实例。解决办法是在应用入口创建一个共享 pinia 实例然后在外部使用时手动传入// src/main.ts export const pinia createPinia() app.use(pinia)// src/router/guard.ts import { pinia } from /main import { useUserStore } from /stores/modules/user router.beforeEach((to, from, next) { const userStore useUserStore(pinia) if (!userStore.token to.path ! /login) { next(/login) } else { next() } })这种写法的要点是useUserStore(pinia)显式传入实例。虽然有点啰嗦但避免了“组件外拿不到 store”的报错也方便单元测试时注入不同的 pinia 实例。5. 常见问题与排查技巧实录最后把我在项目中反复踩过的坑集中列一下这些问题文档里很少写清楚但实际遇到时非常影响开发效率。5.1 解构 store 导致响应式丢失这是 Pinia 最经典的坑症状是“页面第一次渲染正常数据一变页面不动”。原因我已经在前文提过reactive代理的属性一旦被解构成普通变量就脱离了响应式拦截。解决办法是使用storeToRefsimport { storeToRefs } from pinia const userStore useUserStore() const { token, userInfo } storeToRefs(userStore) // 保持响应式 const { login, logout } userStore // action 直接解构没问题注意storeToRefs只对 state 和 getters 有效actions 是普通函数直接解构即可。千万不要在storeToRefs里传 actions会得到一个毛都没有的响应式对象。5.2 $patch 与整体替换 state有些同学喜欢写store.$state newObject来做整组替换这在 Pinia 里会报错或触发警告。因为 store 的 state 对象在创建时就已经被reactive代理整体替换引用等于试图打破这个代理关系。规范做法有两种// 方式一$patch 批量修改 store.$patch({ token: new-token, userInfo: { ...store.userInfo, nickname: 新名字 }, }) // 方式二逐个赋值 store.token new-token store.userInfo { ...store.userInfo, nickname: 新名字 }$patch还有一个回调形式方便写更复杂的逻辑store.$patch((state) { state.tabs state.tabs.filter((tab) tab.path ! targetPath) state.activeTab lastTab })用回调形式时体内的state是响应式的直接改属性没问题。这比拼出一个完整的 state 对象再覆盖要安全得多。5.3 刷新后 store 状态错乱区分“持久化状态”和“临时状态”很多中后台项目会遇到“F5 一闪回到登录页”或“刷新后菜单路由不对”的问题。多数情况下不是代码逻辑错而是持久化配置没覆盖到该保留的状态。典型场景是用户登录后动态生成了可访问路由但这个动态路由列表没有持久化刷新后权限 store 回到空数组于是路由守卫把用户踢回登录页。解决方法就是把permission.routes加入持久化的pick配置里或者结合本地存储重建用户信息和路由。排查时建议开 DevTools 的 Application 面板直接看 localStorage / sessionStorage 里到底有没有你要的数据比在代码里瞎猜高效得多。5.4 警惕多实例 Pinia如果项目里不止一个createPinia()调用或者代码里在多个地方手动实例化 piniastore 的“单例效果”会被打破同一个useUserStore()可能在不同地方拿到不同实例最直接的影响是 A 组件改了状态B 组件看不到。解决办法是保证全应用只有一个createPinia()并且通过app.use(pinia)注册。这个 bug 排查起来特别折磨人因为代码没有任何报错只在运行时表现异常。5.5 关于测试Store 的单测思路给 store 写单测不需要启动浏览器。思路是创建一个全新的 pinia 实例再通过setActivePinia激活它然后调用 store 方法import { createPinia, setActivePinia } from pinia import { useUserStore } from /stores/modules/user beforeEach(() { setActivePinia(createPinia()) }) it(login should set token, async () { vi.mock(/api/auth, () ({ loginApi: vi.fn().mockResolvedValue({ token: mock-token }), })) const store useUserStore() await store.login({ username: admin, password: 123456 }) expect(store.token).toBe(mock-token) })关键点是setActivePinia保证每个测试用例之间 store 状态互相隔离避免环境污染。6. 一些个人建议如果你正在从 Vuex 迁移到 Pinia或者刚接触 Vue3 状态管理我最想强调的一点是先把 option store 写熟再深入 setup store。option store 的结构有迹可循团队协作、代码 review 时更不容易失控等你对响应式原理融会贯通后setup store 的组合式写法会成为你的利器。Vue3 的状态管理不是越复杂越好而是让数据流和组件逻辑的边界足够清晰。另外配置完持久化和 HMR 后记得建一个“状态变更自查清单”登录后该持久化的字段有没有持久化、退出登录后所有 store 是否都 reset、刷新后路由是否还保持原样。这些自动化难以覆盖的场景靠一套明确的手工核对流程往往事半功倍。Pinia 的架构能力很强但真正决定项目长期健壮的还是团队如何使用它的习惯。 
1. 为什么 Pinia 会成为 Vue3 项目的默认选择在 Vue3 Vite 项目里数据流一旦过了“父子组件互传”这个阶段几乎每个人都会遇到同一种尴尬props像瀑布一样往下漏$emit像接力棒一样往回传中间再掺和几个provide/inject、ref、computed代码很快就变成一团乱麻。这时候把共享状态抽离出来交给一层独立仓库统一维护是最直接也最成熟的解法。到了 Vue3 时代这个解决方案已经有了明确答案Pinia。它不是 Vuex 换个马甲而是从 API 设计、类型推导、模块组织到开发体验都为“组合式 API”重新设计的一套状态管理架构。Pinia 设计里最有意思的一点是打破了 Vuex 时代“全局一个仓库、按模块切片”的固定套路。Pinia 天生是多仓库的每个 store 都是一个独立的useXxxStore()函数组件里想用哪个就调用哪个。这带来的架构收益非常实在可以按业务域收敛状态拿到某个模块的代码视觉范围内就能看到这块业务的数据、变更方法、异步请求全在一起不需要在store/modules/a、store/actions/b、store/getters/c之间来回跳。这一条直接改变了多人协作时的心智负担也是我后来在新项目里彻底放弃 Vuex 的最大原因。这篇文章按“架构”的角度来讲不会逐行翻译文档而是讲清楚三件事Pinia 的设计逻辑是什么、在 Vite 工程里怎么组织多 store 才不乱、以及上了生产环境之后会遇到哪些文档里不写的坑。适合正在做后台管理系统、中台项目或者任何需要长期迭代的 Vue3 项目的前端开发者参考。1.1 对比 Vuex不是改版是推倒重来很多从 Vue2 过来的同学第一反应是拿 Pinia 和 Vuex 做等价对比。实际上两者的差距不能只靠“新增了 setup store”来概括我整理了这几个关键维度对比项Vuex 4Piniastore 形态单一 store modules 嵌套多 store 平铺每个 store 独立修改状态commit mutation同步限制严格直接改 state或调用 action无严格约束异步处理action 中可异步仍需 commitaction 本身就是普通函数随意 awaitTypeScript 推导需要大量手写类型与辅助函数store 创建即获得完整类型推导嵌套模块支持 modules 嵌套复杂度高不支持嵌套但可以互相调用结构更扁平插件生态官方插件较少写法笨重持久化等插件轻量易配最关键的是 Mutation 没了。Vuex 当年引入 Mutation是为了配合 DevTools 做时间旅行调试但在简化心智和类型推导面前这件事的收益越来越低。Pinia 直接告诉开发者想改状态就改想写异步就写DevTools 依然能记录每一次变更。这非常符合“组合式 API”的哲学把复杂机制留给框架把简单留给业务代码。1.2 底层原理reactive 与 computed 撑起整座仓库Pinia 说到底是 Vue3 响应式 API 的一层封装。一个 store 的state本质上是reactive(obj)getters是computed的集合actions就是普通函数。理解这一点很多使用时的“直觉”就有了依据为什么直接修改store.count是可以的因为store对象本身是被reactive处理的属性访问会被响应式系统捕获界面自然更新。为什么解构store里的 state 会丢失响应式因为reactive对属性拦截的效果依赖对象引用你把原始值拿出去就脱离了代理对象。为什么$patch能批量更新因为$patch内部会对整个变更对象做一次合并再一次性触发依赖更新比连续多次赋值性能更好也更利于 DevTools 记录为单次变更。源码层面Pinia 在创建 store 时会给每个仓库生成一个唯一id并把 state、getters、actions 挂到一个通过reactive构建的上下文中。所谓 action 里的this指向的就是这个上下文的代理对象。所以你在 action 里写this.count 2和写store.count 2最终执行路径几乎一样。理解这层机制后你会自然明白为什么 setup store 里用ref声明状态也行用reactive声明状态也行因为他们最后都会转换成响应式数据。1.3 两种 store 写法Option Store 与 Setup Store 怎么选Pinia 提供两套定义 API这是初学者最容易纠结的点。我把这两者的取舍说透Option Store用state/getters/actions三个字段定义结构最接近 Vuex写起来规整。优点是代码一眼能认出哪些是数据、哪些是计算属性、哪些是行为适合团队里新人多、希望约定强的场景。Setup Store写法和组件里的setup()几乎一样用ref/reactive/computed声明状态用普通函数定义方法。优点是可以自由使用watch、computed、自定义组合式函数逻辑复用更方便。我的建议是老项目迁移或团队规范强调可读性时用 Option Store新项目、业务逻辑重的场景用 Setup Store。实际上大型项目里两种混用也完全没问题Pinia 不限制。真正要注意的是风格统一别一个模块一种写法会让后来维护的人拿着代码无所适从。2. 工程化落地在 Vite 项目里初始化 Pinia光看理念没用得落到代码里。这一节从零开始讲 Vite 项目里怎么接入 Pinia、目录怎么摆、第一个 store 怎么写才规范。2.1 安装与入口配置Vite 创建的项目默认没有 Pinia安装只需要一条命令npm install pinia # 或者 pnpm add pinia安装完成后修改项目的入口文件main.ts或main.js把 Pinia 挂到应用实例上import { createApp } from vue import { createPinia } from pinia import App from ./App.vue const app createApp(App) const pinia createPinia() app.use(pinia) app.mount(#app)这里有一个容易被忽略的细节createPinia()生成的实例是一个 Vue 插件但它在内部会注册一个全局的provide把 pinia 实例注入到所有组件。所以组件里调用useStore()时不需要手动传 pinia 实例——只要你在app.use(pinia)之后通过组件渲染链访问它都能自动找到。但如果要在组件外使用 store比如路由守卫、工具函数就得手动把 pinia 实例传进去这个坑后面专门讲。2.2 目录结构多 store 的推荐组织方式Pinia 没有强制的目录规范我基于多个中后台项目的实践推荐这样组织src/ ├── stores/ │ ├── index.ts # 统一导出方便引用 │ ├── modules/ │ │ ├── user.ts # 用户信息、登录态 │ │ ├── app.ts # 侧边栏、主题、布局状态 │ │ ├── permission.ts # 权限、路由表 │ │ ├── tabs.ts # 多标签页导航 │ │ └── settings.ts # 系统设置 │ └── plugins/ │ └── persist.ts # 持久化插件封装这里的关键思路是按业务域而不是按数据类型来划分文件。比如不要搞state.ts、actions.ts这种按角色分的目录因为一个业务变更通常会同时改数据、方法和计算属性拆开反而增加查找成本。按模块拆分后每个文件内部再按state/getters/actions组织内容读起来才顺。2.3 第一个完整 store以用户登录态为例拿中后台最常见的用户模块来展示一个接近生产质量的 store// src/stores/modules/user.ts import { defineStore } from pinia import { loginApi, getUserInfoApi, logoutApi } from /api/auth import { storage } from /utils/storage export const useUserStore defineStore(user, { state: () ({ token: storage.get(token) || , userInfo: {} as UserInfo, roles: [] as string[], }), getters: { isLogin: (state) !!state.token, displayName: (state) state.userInfo?.nickname || state.userInfo?.username || 未登录, }, actions: { async login(payload: LoginParams) { const { token } await loginApi(payload) this.token token storage.set(token, token) }, async fetchUserInfo() { const data await getUserInfoApi() this.userInfo data.userInfo this.roles data.roles ?? [] }, async logout() { await logoutApi() this.reset() }, reset() { this.token this.userInfo {} this.roles [] storage.remove(token) }, }, })这个例子里有几个值得展开的点state 用函数返回初始值和组件 data 保持一致好处是每次创建 store 都能拿到新的初始状态测试和复用更安心。getters 里返回新对象或经过计算的值比如displayName汇总了多个字段组件里拿到它就不需要再写一遍if else。action 里直接访问thisOption Store 约束下的this就是 store 实例类型推导在编辑器中会直接提示不需要额外声明返回值类型。reset()方法做成 action可以一次性把所有状态恢复为初始值。登录过期、切换账号这类场景只要调用一次store.reset()不会遗漏任何字段。3. 模块化状态管理架构实操到了这一步多 store 之间如何协动、数据流怎么设计就是架构的核心了。这一节用真实后台系统的拆法做案例。3.1 典型后台系统的拆法一份可复用的模块对照表后台管理系统是 Pinia 最常见的应用场景。我一般按下面的方式拆模块模块名称负责的状态典型 actions典型 gettersusertoken、用户信息、角色login / fetchUserInfo / logoutisLogin、displayNamepermission路由表、按钮权限、菜单树generateRoutes / resetaccessibleRoutestabs多标签页列表、当前激活页addTab / removeTab / closeOtherscachedViewsapp侧边栏展开收起、设备类型、全局 loadingtoggleSidebar / setDevicesidebarOpenedsettings主题色、布局模式、语言、水印setTheme / setLayout / setLanguagethemeStyle这个划分有个核心原则每个模块只关心自己的一组内聚状态模块之间可以通过调用对方的方法协作但不直接修改对方 state。比如登录成功后user store 拿到了角色信息接下来要把角色同步给 permission store 去生成可访问路由。正确的做法是在 user 的 action 里调用 permission store 的 action或者由页面组件编排两者的调用顺序而不是 user 直接把 permission 的数据给写了。这样每一块状态都有唯一“责任人”排查问题时能迅速锁定。3.2 store 之间互相调用与依赖顺序一个 store 内部调用另一个 store在 Pinia 里非常自然直接useOtherStore()即可// src/stores/modules/permission.ts import { useUserStore } from ./user export const usePermissionStore defineStore(permission, { state: () ({ routes: [] as RouteRecordRaw[], }), actions: { async generateRoutes() { const userStore useUserStore() const roles userStore.roles // 根据角色过滤动态路由 const accessedRoutes filterAsyncRoutes(asyncRoutes, roles) this.routes accessedRoutes }, }, })注意这里有一个store 必须已被创建的时序问题在 script 顶层或组件setup()里调用usePermissionStore()时组件渲染链已经能提供 pinia 实例所以没问题。但如果是在 store 的state初始化函数里直接调用另一个 store就会报“getActivePinia was called with no active Pinia”的错。解决办法是不要在 state 初始化里调用其他 store应该放到 action 或 getter 里再取。getter 因为执行时机晚反而安全。3.3 Setup Store 高阶用法复用组合式函数前面提到 Setup Store 可以自由使用组合式函数这里给一段实际代码// src/stores/modules/device.ts import { ref } from vue import { useEventListener } from vueuse/core import { defineStore } from pinia export const useDeviceStore defineStore(device, () { const width ref(window.innerWidth) const isMobile ref(false) function update() { width.value window.innerWidth isMobile.value width.value 768 } useEventListener(window, resize, update) update() return { width, isMobile } })在这个文件里useEventListener会在 store 创建时自动注册监听销毁时自动清理。这要比在组件里写一堆addEventListener/removeEventListener干净得多。更重要的是width和isMobile天然是响应式的任何组件调用useDeviceStore()都能同步获得最新的窗口状态。3.4 数据流的职责边界store 与组件该各管什么状态管理架构最模糊的边界在于“哪些数据该进 store哪些留在组件里”。我的判断标准很简单多组件共享的数据进 store纯组件内部 UI 状态留在组件内。比如弹窗的visible、表单的临时输入值、列表的筛选条件这些通常不需要全局共享放进 store 只会徒增噪音。反过来登录态、权限列表、用户偏好、全局主题这类被多处依赖的状态放到 store 是合理的。另外注意store 不该被当成“万能请求层”。一份只服务于某个表格的数据直接在组件里的onMounted请求并存在ref中就好除非数据在多个不相关的组件里都要用或者需要缓存复用才放进 store。这个原则能帮整个项目保持轻盈避免 store 文件越来越大、越来越杂。4. 持久化、HMR 与生产环境进阶状态管理到了生产环境躲不开几个现实问题刷新页面后状态不能丢、开发时的热更新不能把 store 状态弄丢、敏感数据不能明文存在 localStorage。这一节讲透。4.1 持久化方案使用 pinia-plugin-persistedstate官方没有默认带上持久化能力社区最常用的是pinia-plugin-persistedstate。安装配置很简单npm install pinia-plugin-persistedstate// src/stores/index.ts import { createPinia } from pinia import piniaPluginPersistedstate from pinia-plugin-persistedstate const pinia createPinia() pinia.use(piniaPluginPersistedstate) export default pinia然后在具体 store 里开启export const useUserStore defineStore(user, { state: () ({ token: , userInfo: {} }), persist: { key: my-app-user, storage: sessionStorage, // 按需选择 localStorage / sessionStorage pick: [token, userInfo], // 只持久化指定字段 }, // ... })这里有三个经验之谈pick 字段时只保留真正需要“跨刷新”的数据。比如token和userInfo需要保留但临时的下拉列表数据没必要。考虑用sessionStorage而不是localStorage存敏感信息。localStorage会永久保留而用户关闭浏览器后sessionStorage自动清理安全边界更好。不要在 store 里直接存大体积数据比如完整的用户列表、文件 base64持久化插件会把它们序列化到浏览器存储里刷新一次就占一次内存性能和隐私都受影响。4.2 HMR 热更新开发时不丢 stateVite 的开发服务器天然支持热更新但 store 模块的热更新有讲究。Pinia 官方提供了一个模式在 store 文件底部加上import { acceptHMRUpdate, defineStore } from pinia if (import.meta.hot) { import.meta.hot.accept(acceptHMRUpdate(useUserStore, import.meta.hot)) }这段代码的作用是当user.ts文件被修改时让 Vite 只替换 user store 的定义而不是销毁整个应用再重新渲染。如果不加HMR 可能会重建所有 store导致你手动修改过的状态比如登录态在编辑器保存瞬间被清空调试成本立刻飙升。建议每个 store 文件都加上这段不要偷懒。4.3 组件外使用 store路由守卫与工具函数在路由守卫里判断登录态、在 axios 拦截器里读取 token都是很常见的需求。但这些代码不在组件渲染链里直接useUserStore()会找不到 pinia 实例。解决办法是在应用入口创建一个共享 pinia 实例然后在外部使用时手动传入// src/main.ts export const pinia createPinia() app.use(pinia)// src/router/guard.ts import { pinia } from /main import { useUserStore } from /stores/modules/user router.beforeEach((to, from, next) { const userStore useUserStore(pinia) if (!userStore.token to.path ! /login) { next(/login) } else { next() } })这种写法的要点是useUserStore(pinia)显式传入实例。虽然有点啰嗦但避免了“组件外拿不到 store”的报错也方便单元测试时注入不同的 pinia 实例。5. 常见问题与排查技巧实录最后把我在项目中反复踩过的坑集中列一下这些问题文档里很少写清楚但实际遇到时非常影响开发效率。5.1 解构 store 导致响应式丢失这是 Pinia 最经典的坑症状是“页面第一次渲染正常数据一变页面不动”。原因我已经在前文提过reactive代理的属性一旦被解构成普通变量就脱离了响应式拦截。解决办法是使用storeToRefsimport { storeToRefs } from pinia const userStore useUserStore() const { token, userInfo } storeToRefs(userStore) // 保持响应式 const { login, logout } userStore // action 直接解构没问题注意storeToRefs只对 state 和 getters 有效actions 是普通函数直接解构即可。千万不要在storeToRefs里传 actions会得到一个毛都没有的响应式对象。5.2 $patch 与整体替换 state有些同学喜欢写store.$state newObject来做整组替换这在 Pinia 里会报错或触发警告。因为 store 的 state 对象在创建时就已经被reactive代理整体替换引用等于试图打破这个代理关系。规范做法有两种// 方式一$patch 批量修改 store.$patch({ token: new-token, userInfo: { ...store.userInfo, nickname: 新名字 }, }) // 方式二逐个赋值 store.token new-token store.userInfo { ...store.userInfo, nickname: 新名字 }$patch还有一个回调形式方便写更复杂的逻辑store.$patch((state) { state.tabs state.tabs.filter((tab) tab.path ! targetPath) state.activeTab lastTab })用回调形式时体内的state是响应式的直接改属性没问题。这比拼出一个完整的 state 对象再覆盖要安全得多。5.3 刷新后 store 状态错乱区分“持久化状态”和“临时状态”很多中后台项目会遇到“F5 一闪回到登录页”或“刷新后菜单路由不对”的问题。多数情况下不是代码逻辑错而是持久化配置没覆盖到该保留的状态。典型场景是用户登录后动态生成了可访问路由但这个动态路由列表没有持久化刷新后权限 store 回到空数组于是路由守卫把用户踢回登录页。解决方法就是把permission.routes加入持久化的pick配置里或者结合本地存储重建用户信息和路由。排查时建议开 DevTools 的 Application 面板直接看 localStorage / sessionStorage 里到底有没有你要的数据比在代码里瞎猜高效得多。5.4 警惕多实例 Pinia如果项目里不止一个createPinia()调用或者代码里在多个地方手动实例化 piniastore 的“单例效果”会被打破同一个useUserStore()可能在不同地方拿到不同实例最直接的影响是 A 组件改了状态B 组件看不到。解决办法是保证全应用只有一个createPinia()并且通过app.use(pinia)注册。这个 bug 排查起来特别折磨人因为代码没有任何报错只在运行时表现异常。5.5 关于测试Store 的单测思路给 store 写单测不需要启动浏览器。思路是创建一个全新的 pinia 实例再通过setActivePinia激活它然后调用 store 方法import { createPinia, setActivePinia } from pinia import { useUserStore } from /stores/modules/user beforeEach(() { setActivePinia(createPinia()) }) it(login should set token, async () { vi.mock(/api/auth, () ({ loginApi: vi.fn().mockResolvedValue({ token: mock-token }), })) const store useUserStore() await store.login({ username: admin, password: 123456 }) expect(store.token).toBe(mock-token) })关键点是setActivePinia保证每个测试用例之间 store 状态互相隔离避免环境污染。6. 一些个人建议如果你正在从 Vuex 迁移到 Pinia或者刚接触 Vue3 状态管理我最想强调的一点是先把 option store 写熟再深入 setup store。option store 的结构有迹可循团队协作、代码 review 时更不容易失控等你对响应式原理融会贯通后setup store 的组合式写法会成为你的利器。Vue3 的状态管理不是越复杂越好而是让数据流和组件逻辑的边界足够清晰。另外配置完持久化和 HMR 后记得建一个“状态变更自查清单”登录后该持久化的字段有没有持久化、退出登录后所有 store 是否都 reset、刷新后路由是否还保持原样。这些自动化难以覆盖的场景靠一套明确的手工核对流程往往事半功倍。Pinia 的架构能力很强但真正决定项目长期健壮的还是团队如何使用它的习惯。