用途：Pinia v3 是 Vue 官方状态管理库，用于 Vue 3（Vue 2.7 需配合 @vue/composition-api）项目中的全局状态管理，文档覆盖基础用法、SSR、测试与 Vuex 迁移。
主要能力：
- 使用 defineStore 定义 store，支持 Option Stores（类似 Options API，含内置 $reset()）与 Setup Stores（Composition API 风格，可集成 composables）两种写法。
- 提供 state、getters、actions 三类概念：直接读写 state、用 $patch 批量更新、用 $reset 重置（仅 Option Store）；getters 为计算属性；actions 承载业务逻辑并可为异步。
- 支持插件（pinia.use）、组件外访问 store、HMR（acceptHMRUpdate）、DevTools 时间旅行调试、测试（@pinia/testing 的 createTestingPinia、setActivePinia）。
必要用法： bun add pinia 安装后先 createPinia() 并 app.use(pinia)，再 mount 应用；每个应用仅一个 Pinia 实例（SSR 除外）。组件内解构 state/getters 必须用 storeToRefs() 保持响应性；actions 可直接解构。组件外（如路由守卫）须在回调函数内调用 useStore()，SSR 下可显式传入 pinia 实例。Nuxt 集成命令为：bunx nuxi@latest module add pinia。测试每个用例前执行 setActivePinia(createPinia())。
适用场景：Vue 3 / Nuxt 项目的状态管理、SSR hydration、从 Vuex 迁移、单元与组件测试、持久化或日志类插件。
限制与已知注意事项：不能在 store 创建后动态新增响应式 state 属性；不要直接解构 store；actions 不要用箭头函数；Setup Store 必须返回全部 state；SSR 序列化建议用 devalue 而非 JSON.stringify；异步 action 中须在 await 前调用 useStore()；避免 store 之间循环依赖；使用 this 的 getter 需显式标注返回类型。文档列有 12 类常见问题及预防方式，并附官方文档与参考文件索引。