Vue3 状态管理方案：Pinia 全指南

📦 Vue3 状态管理方案：Pinia 全指南

Pinia 是 Vue 官方推荐的下一代状态管理库，完全替代 Vuex，支持 Vue3 Composition API、TypeScript 友好、轻量灵活。本文从基础使用、核心 API、高级技巧、注意事项、常见坑五个维度全面讲解。

一、快速上手：安装与基础使用

1. 安装方式

（1）Vite/Vue CLI 项目

# npmnpminstallpinia# yarnyarnaddpinia# pnpmpnpmaddpinia

（2）CDN 引入

<scriptsrc="https://unpkg.com/pinia@2.1.7/dist/pinia.iife.js"></script><script>const{createPinia}=Pinia</script>

2. 初始化 Pinia

在main.ts中注册 Pinia：

import{createApp}from'vue'import{createPinia}from'pinia'importAppfrom'./App.vue'constapp=createApp(App)constpinia=createPinia()app.use(pinia)// 注册 Piniaapp.mount('#app')

3. 创建第一个 Store

Pinia 中没有modules，每个 Store 都是独立的，通过defineStore定义：

（1）选项式写法（类似 Vuex）

// src/stores/counter.tsimport{defineStore}from'pinia'// 第一个参数是 Store 的唯一 ID（必须全局唯一）exportconstuseCounterStore=defineStore('counter',{// 状态：返回初始状态的函数state:()=>({count:0,name:'Pinia'}),// 计算属性：类似 Vue 的 computed，自动缓存getters:{doubleCount:(state)=>state.count*2,// 访问其他 getters 用 this（需指定返回值类型）doubleCountPlusOne():number{returnthis.doubleCount+1}},// 动作：支持同步/异步，修改状态的唯一推荐方式actions:{increment(){this.count++},asyncfetchData(){constres=awaitfetch('/api/data')constdata=awaitres.json()this.name=data.name}}})

（2）组合式写法（Vue3 Composition API）

更灵活，适合复杂场景：

// src/stores/user.tsimport{defineStore}from'pinia'import{ref,computed}from'vue'exportconstuseUserStore=defineStore('user',()=>{// 状态：用 ref/reactive 定义constuserInfo=ref({name:'',age:0})consttoken=ref('')// 计算属性：用 computed 替代 gettersconstisAdult=computed(()=>userInfo.value.age>=18)// 动作：普通函数，支持同步/异步constupdateUser=(info:{name:string;age:number})=>{userInfo.value=info}constlogin=async(username:string,password:string)=>{constres=awaitfetch('/api/login',{method:'POST',body:JSON.stringify({username,password})})constdata=awaitres.json()token.value=data.token}// 返回需要暴露的属性和方法return{userInfo,token,isAdult,updateUser,login}})

二、核心 API 详解

1. Store 实例属性

2. Getters 特性

• 缓存机制：只有依赖的状态变化时才重新计算；
• 访问其他 Store：在 getters 中可以调用其他 Store 实例；

  import{useCounterStore}from'./counter'getters:{crossStoreCount(state){constcounterStore=useCounterStore()returnstate.count+counterStore.count}}

• 传递参数：getters 返回函数实现参数传递（此时不会缓存结果）；

  getters:{getCountByMultiplier:(state)=>(multiplier:number)=>state.count*multiplier}// 组件中调用：store.getCountByMultiplier(3)

3. Actions 特性

• 支持异步：直接在 actions 中使用async/await；
• 修改状态：可直接修改this.count或用$patch；
• 访问其他 Store：同 getters，直接在 actions 中调用其他 Store；
• 错误处理：可通过try/catch或$onAction监听错误。

三、组件中使用 Store

1. Setup 语法糖（推荐）

<template> <div>{{ count }}</div> <button @click="increment">+1</button> </template> <script setup lang="ts"> import { useCounterStore } from '@/stores/counter' import { storeToRefs } from 'pinia' // 获取 Store 实例 const counterStore = useCounterStore() // 直接访问状态/动作 const increment = () => counterStore.increment() // 解构状态时必须用 storeToRefs 保持响应式！ const { count, doubleCount } = storeToRefs(counterStore) </script>

2. 选项式 API 兼容

适合老项目迁移：

<script lang="ts"> import { useCounterStore } from '@/stores/counter' import { mapState, mapActions, mapGetters } from 'pinia' export default { computed: { ...mapState(useCounterStore, ['count', 'name']), ...mapGetters(useCounterStore, ['doubleCount']) }, methods: { ...mapActions(useCounterStore, ['increment']) }, mounted() { this.increment() } } </script>

四、高级技巧

1. Store 持久化（插件）

使用pinia-plugin-persistedstate实现状态持久化到 localStorage/sessionStorage：

安装

npminstallpinia-plugin-persistedstate

配置

// main.tsimport{createPinia}from'pinia'importpersistedstatefrom'pinia-plugin-persistedstate'constpinia=createPinia()pinia.use(persistedstate)

在 Store 中启用

// 选项式写法exportconstuseCounterStore=defineStore('counter',{state:()=>({count:0}),persist:true// 全局默认配置（localStorage）// 自定义配置// persist: {// key: 'counter-store',// storage: sessionStorage,// paths: ['count'] // 仅持久化count字段// }})// 组合式写法exportconstuseUserStore=defineStore('user',()=>{constuserInfo=ref({})return{userInfo}},{persist:true})

2. Store 模块化拆分

按业务模块拆分 Store，如user.ts、cart.ts、setting.ts，通过目录结构管理：

src/stores/ ├── index.ts # 导出所有Store ├── user.ts # 用户模块 ├── cart.ts # 购物车模块 └── setting.ts # 设置模块

index.ts统一导出：

export*from'./user'export*from'./cart'export*from'./setting'

3. Pinia 插件开发

自定义插件扩展 Store 功能，比如添加日志、全局状态监听：

// src/plugins/pinia-logger.tsexportconstpiniaLogger=({store})=>{store.$subscribe((mutation,state)=>{console.log(`[Pinia Logger]${mutation.storeId}状态变化:`,mutation.payload,state)})store.$onAction(({name,args,after,onError})=>{console.log(`[Pinia Logger] 调用动作:${name}, 参数:`,args)after((result)=>{console.log(`[Pinia Logger] 动作完成:${name}, 返回值:`,result)})onError((error)=>{console.error(`[Pinia Logger] 动作失败:${name}, 错误:`,error)})})}// main.ts 注册插件pinia.use(piniaLogger)

五、注意事项

1. 响应式处理

• 禁止直接解构 Store：直接解构会丢失响应式，必须用storeToRefs；
• 修改状态的推荐方式：优先用actions，其次用$patch，不推荐直接修改store.count = 10（虽然语法允许，但不利于调试和维护）；
• 组合式写法中的响应式：用ref/reactive定义状态，确保响应式。

2. TypeScript 支持

• 状态类型自动推断：选项式写法中 Pinia 会自动推断state的类型；
• 组合式写法需手动定义类型：复杂对象建议用接口定义：

  interfaceUserInfo{name:string;age:number;}constuserInfo=ref<UserInfo>({name:'',age:0})

• Actions 参数类型：明确参数类型，避免隐式 any。

3. 性能优化

• Getters 缓存：合理利用 getters 的缓存特性，避免重复计算；
• 批量修改状态：用$patch批量修改，减少响应式更新次数；
• 避免在 actions 中执行大量同步计算：复杂计算建议放到 getters 或单独的工具函数中。

六、开发中常见的坑

1. 解构 Store 丢失响应式

❌ 错误写法：

const{count}=useCounterStore()// count 是普通值，不会响应式更新

✅ 正确写法：

import{storeToRefs}from'pinia'const{count}=storeToRefs(useCounterStore())// count 是 ref，保持响应式

2. 组合式写法中无法使用$reset

选项式写法的$reset是自动生成的，组合式写法需手动实现：

exportconstuseCounterStore=defineStore('counter',()=>{constcount=ref(0)// 手动实现重置函数constreset=()=>{count.value=0}return{count,reset}})

3. 持久化插件不生效

• 确保插件已正确注册到 Pinia；
• 组合式写法中，必须在defineStore的第三个参数中配置persist: true；
• 如果状态包含复杂对象（如 Date、Map），需配置serializer自定义序列化：

  persist:{serializer:{serialize:(value)=>JSON.stringify(value,(key,val)=>{if(valinstanceofDate)returnval.toISOString()returnval}),deserialize:(value)=>JSON.parse(value,(key,val)=>{if(key==='createTime')returnnewDate(val)returnval})}}

4. 在组件外使用 Store 实例

❌ 错误写法（组件外直接调用 Store，可能导致 Pinia 未初始化）：

// src/utils/api.tsimport{useUserStore}from'@/stores/user'constuserStore=useUserStore()// 组件外调用，可能报错asyncfunctionfetchData(){consttoken=userStore.token}

✅ 正确写法（在函数内部调用 Store）：

asyncfunctionfetchData(){constuserStore=useUserStore()// 函数内部调用，确保 Pinia 已初始化consttoken=userStore.token}

5. Getters 中使用this丢失类型

选项式写法中，getters 用箭头函数会丢失this类型，需用普通函数：
❌ 错误写法：

getters:{doubleCount:()=>this.count*2// this 类型为 any}

✅ 正确写法：

getters:{doubleCount():number{// 必须指定返回值类型returnthis.count*2}}

七、Pinia vs Vuex 对比

Pinia 完全替代 Vuex，是 Vue3 状态管理的首选方案！