Pinia 备忘清单深度解析：Vue 状态管理从安装、Store 到持久化与测试（jaywcjlove/reference）

文档知识库教程开发工具【免费下载链接】reference为开发人员分享快速参考备忘清单(速查表)项目地址https://gitcode.com/jaywcjlove/reference点击查看免费下载Pinia 是 Vue 官方推荐的下一代状态管理库它以简洁的 API、完整的 TypeScript 支持和模块化的 store 设计成为 Vue 3 生态中替代 Vuex 的首选方案。本文基于 jaywcjlove/reference 仓库中的 Pinia 备忘清单 展开深度讲解覆盖从安装接入、Store 定义、组件消费、热重载与 Devtools 调试到插件扩展、状态持久化、SSR、异步 Actions 与单元测试的完整实战链路帮助你在一份速查式指南中掌握 Pinia 的日常高频用法。一、这份备忘清单在仓库中的位置在 jaywcjlove/reference 仓库中Pinia 被归类在 Vue 生态之下README.md 的 Vue 区块里以绿色标签形式列出了 Pinia与其相邻的是 Vue 3 与 Vue 2 备忘清单。仓库为 Pinia 准备了专属图标 assets/pinia.svg。值得留意的是Vue 3 备忘清单 在介绍官方脚手架create-vue时交互式提问中便包含了Add Pinia for state management? … No/Yes说明 Pinia 已是 Vue 3 项目脚手架的一等公民勾选后即可自动接入。因此阅读本文前建议先浏览 Vue 3 备忘清单 了解应用骨架的搭建。此外仓库通过refs-cli见 package.json 的build/start脚本将 Markdown 渲染为站点页面文档中出现的!--rehype:wrap-class...--、!--rehype:style...--等注释即是为该渲染器提供的布局与样式注解如col-span-2 row-span-2控制卡片栅格占位不影响读者直接阅读源码中的技术内容。二、安装 Pinia 并创建实例安装命令Pinia 以独立包形式分发可通过任一主流包管理器安装npm install pinia # or yarn add pinia # or pnpm add pinia创建 Pinia 实例并挂载到 Vue 应用安装完成后需要在应用入口创建 Pinia 实例并通过app.use(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)在你的 Vue 应用中createPinia()返回的实例既是插件也是后续所有 store 的共享上下文载体app.use(pinia)之后组件内即可通过useXxxStore()组合式函数访问对应 store。三、定义 StoreOptions API 风格核心三要素state / getters / actions创建一个 store 文件例如src/stores/counter.js并使用defineStore定义storeimport { defineStore } from pinia export const useCounterStore defineStore(counter, { state: () ({ count: 0 }), actions: { increment() { this.count } }, getters: { doubleCount: (state) state.count * 2 } })三个配置项各自承担不同职责state定义响应式数据的初始值必须是返回对象的函数以保证每个 store 实例拥有独立的数据副本actions定义修改状态的方法。与 Vuex 不同Pinia 的 actions 不再需要显式 commit/mutation直接通过this.count修改即可且 actions 内可使用this访问整个 store包括其他 actions 与 gettersgetters定义基于 state 的派生值类似 Vue 的computed。上述示例中doubleCount接收state作为参数并返回state.count * 2组件中读取时无需括号。Modules 模式放弃嵌套模块改用独立文件Pinia 不使用传统的 Vuex 模块模式嵌套modules: {}而是推荐将每个 store 拆分为独立的 store 文件每个文件通过defineStore定义唯一命名如user、counter// src/stores/user.js import { defineStore } from pinia export const useUserStore defineStore(user, { state: () ({ name: Alice, age: 25 }), actions: { setName(name) { this.name name } }, getters: { isAdult: (state) state.age 18 } })这种设计消除了 Vuex 时代的模块命名空间namespaced配置成本——每个文件天然就是一个独立命名空间store 之间需要协作时直接相互调用对方的useXxxStore()即可代码组织和依赖关系都更加直观。四、在组件中使用 Store在setup()中直接消费在组件中调用useCounterStore()即可获得 store 实例其 state、getters、actions 会作为响应式属性与方法暴露给模板template div pCount: {{ counterStore.count }}/p pDouble Count: {{ counterStore.doubleCount }}/p button clickcounterStore.incrementIncrement/button /div /template script import { useCounterStore } from /stores/counter export default { setup() { const counterStore useCounterStore() return { counterStore } } } /script注意模板中建议整体返回counterStore对象再通过counterStore.xxx访问避免解构导致响应性丢失若确需解构请配合storeToRefs使用详见 Pinia 官方文档。使用 Options API如果你更喜欢 Options API同样可以在setup()中获取 store 并返回给模板使用script import { defineComponent } from vue import { useCounterStore } from /stores/counter export default defineComponent({ setup() { const counterStore useCounterStore() return { counterStore } } }) /script无论组件采用script setup、setup()组合式 API 还是 Options APIPinia 的接入方式都保持一致——在setup阶段调用useXxxStore()从而与 Vue 的响应式系统无缝衔接。将 Store 封装进组合函数你可以将 store 与组合函数一起使用把取 store 派生数据 操作封装成可复用的逻辑单元// src/composables/useCounter.js import { useCounterStore } from /stores/counter export function useCounter() { const counterStore useCounterStore() return { count: counterStore.count, doubleCount: counterStore.doubleCount, increment: counterStore.increment } }这样组件只需const { count, doubleCount, increment } useCounter()即可获得一整套与计数器相关的状态与操作适合在多处复用的业务逻辑中应用。五、开发体验热重载与 Vue DevtoolsVite 下的热重载HMR使用 Vite 时你可以启用热重载功能使编辑 store 后无需刷新页面即可保留当前状态if (import.meta.hot) { import.meta.hot.accept(acceptHMRUpdate(useCounterStore, import.meta.hot)) }acceptHMRUpdate由 Pinia 导出接收当前 store 的useXxxStore函数与import.meta.hot对象将该段代码置于 store 文件底部即可在开发模式下让 store 与组件一起热更新。使用 Vue Devtools 调试Pinia 可以与 Vue Devtools 一起使用。确保你安装了最新版本的 Vue Devtools然后你可以在 Devtools 中查看和调试你的 Pinia store——包括查看各 store 的 state 快照、追踪 action 调用、时间旅行式地观察状态变更调试体验与 Vuex 时期相当甚至更直观。六、插件机制与状态持久化编写插件扩展 PiniaPinia 支持插件通过pinia.use(plugin)注册。插件接收包含store的上下文对象可用于监听 action、扩展 store 属性或注入全局逻辑// src/plugins/piniaPlugin.js export function piniaPlugin({ store }) { store.$onAction(({ name, store, args, after, onError }) { console.log(Action ${name} was called with args:, args) }) } // main.js import { createPinia } from pinia import { piniaPlugin } from ./plugins/piniaPlugin const pinia createPinia() pinia.use(piniaPlugin)$onAction是 Pinia 提供的 action 钩子订阅 API回调中可拿到 action 名称name、参数args以及after成功后回调与onError失败后回调两个注册器非常适合做日志埋点、请求统计或权限校验等横切关注点。所有 store 都会自动获得通过pinia.use()注册的插件能力。使用pinia-plugin-persist持久化状态为了让 store 状态在刷新后依然保留社区常用pinia-plugin-persist插件实现 localStorage/sessionStorage 持久化完整流程分四步。1. 安装插件npm install pinia-plugin-persist2. 配置 Pinia 和pinia-plugin-persist在入口文件中注册插件。⚠️ Vue 2 项目需要额外接入vue/composition-api与PiniaVuePluginimport Vue from vue import vueCompositionApi from vue/composition-api import { createPinia, PiniaVuePlugin } from pinia import piniaPersist from pinia-plugin-persist import App from ./App.vue Vue.use(vueCompositionApi) Vue.use(PiniaVuePlugin) const pinia createPinia() pinia.use(piniaPersist) new Vue({ pinia, render: h h(App) }).$mount(#app)Vue 3 项目直接通过app.use(pinia)挂载import { createApp } from vue import { createPinia } from pinia import piniaPersist from pinia-plugin-persist import App from ./App.vue const pinia createPinia() pinia.use(piniaPersist) createApp(App) .use(pinia) .mount(#app)3. 创建 Store 并启用持久化在 store 的第三层配置persist选项enabled: true开启持久化strategies数组可精确控制存储介质与需要持久化的字段路径// stores/userStore.js import { defineStore } from pinia export const useUserStore defineStore(userStore, { state: () ({ firstName: S, lastName: L, accessToken: xxxxxxxxxxxxx }), actions: { setToken(value) { this.accessToken value } }, persist: { enabled: true, strategies: [ { storage: localStorage, paths: [accessToken] } ] } })配置要点storage指定持久化介质常用localStorage或sessionStorage默认一般为localStoragepaths指定要持久化的 state 路径数组例如[accessToken]表示仅持久化accessToken字段其余字段如本例中的姓名不落盘从而实现敏感数据随刷新保留、非必要数据不占空间的精细化控制若不配置paths插件会默认持久化整个 state。4. 在组件中使用持久化的 Store组件中的使用方式与普通 store 完全一致刷新页面后accessToken会自动从存储介质中恢复// src/components/SomeComponent.vue template div p{{ userStore.firstName }} {{ userStore.lastName }}/p p{{ userStore.accessToken }}/p /div /template script import { useUserStore } from /stores/userStore export default { setup() { const userStore useUserStore() return { userStore } } } /script七、SSR 支持Pinia 支持服务端渲染 (SSR)。由于 SSR 下每个请求都需要独立的 store 实例避免请求间状态串扰正确做法是在工厂函数createApp()内创建 Pinia 实例而不是在模块顶层创建import { createPinia } from pinia export function createApp() { const app createSSRApp(App) const pinia createPinia() app.use(pinia) return { app, pinia } }将{ app, pinia }一并返回服务端渲染时即可按请求实例化独立的应用与状态容器配合pinia-plugin-persist等插件时SSR 场景还需注意避免在服务端访问浏览器专有的localStorage通常需要针对服务端禁用或替换持久化策略。八、使用异步 ActionsPinia 支持在 actions 中使用异步代码actions可以是async函数内部可直接await异步请求并更新 state// src/stores/todo.js import { defineStore } from pinia import axios from axios export const useTodoStore defineStore(todo, { state: () ({ todos: [] }), actions: { async fetchTodos() { const response await axios.get(/api/todos) this.todos response.data } } })组件中通过todoStore.fetchTodos()触发请求请求完成后todos自动更新并驱动视图刷新由于 actions 返回 Promise组件内还可以进一步await或使用.then()处理加载完成后的后续逻辑。相比 Vuex 中需要借助 async/await 手动编排 mutation 的方式Pinia 的异步 action 写法与普通业务函数无异。九、测试 Pinia Store你可以使用 Vue Test Utils 和 Jest 来测试 Pinia store。核心要点是在每个测试用例前通过setActivePinia(createPinia())创建并激活一个全新的 Pinia 实例保证用例之间状态隔离// __tests__/counterStore.test.js import { setActivePinia, createPinia } from pinia import { useCounterStore } from /stores/counter describe(Counter Store, () { beforeEach(() { setActivePinia(createPinia()) }) it(increments the count, () { const counterStore useCounterStore() expect(counterStore.count).toBe(0) counterStore.increment() expect(counterStore.count).toBe(1) }) it(returns double count, () { const counterStore useCounterStore() counterStore.count 2 expect(counterStore.doubleCount).toBe(4) }) })测试要点setActivePinia用于为当前测试环境设置活动的 Pinia 实例此后调用useCounterStore()均从该实例解析 store通过beforeEach重建实例可确保每个用例都从干净的初始状态count 0开始测试中可以直接读写 state如counterStore.count 2并断言 getters 的计算结果无需挂载组件即可完成纯逻辑验证对于异步 actions可使用await counterStore.fetchTodos()后再断言更新后的 state。十、延伸阅读Vue 3 备忘清单Pinia 通常与之配套使用其中包含create-vue脚手架接入 Pinia 的交互式配置流程Vue 2 备忘清单在 Vue 2 项目中使用 Pinia 时的配套参考仓库首页 README查看 Pinia 在仓库 Vue 生态分类中的完整索引。赞分享文档知识库教程开发工具【免费下载链接】reference为开发人员分享快速参考备忘清单(速查表)项目地址https://gitcode.com/jaywcjlove/reference点击查看免费下载相关推荐Pinia 状态管理完整速查Store 定义、插件持久化与 SSR 实战Quick Reference 备忘清单详解Pinia 状态管理完整速查Store 定义、插件持久化与 SSR 实战Quick Reference 备忘清单详解 本篇技术指南基于 Quick Ref文档教程HTTP 状态码快速参考备忘清单jaywcjlove/reference 速查表HTTP 状态码快速参考备忘清单jaywcjlove/reference 速查表 本指南以 jaywcjlove/reference https://lin文档知识库教程开发工具JavaScript 速查表jaywcjlove/reference 中的 JavaScript 备忘清单全解析JavaScript 速查表jaywcjlove/reference 中的 JavaScript 备忘清单全解析 本指南以开源仓库 jaywcjlove/re文档知识库教程开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考