看到“5. pinia 小菠萝大菠萝都是菠萝”这个项目标题我第一反应是这兄弟是在写绕口令还是在给前端状态管理库起花名点进去一看果然是在说 Pinia。对 Vue 开发者来说pinia 这个词已经不陌生了它就是 Vue 官方钦定的下一代状态管理库。名字里带个“pinia”其实是菠萝pineapple的词根所以大家习惯叫它“小菠萝”。标题里的“大菠萝”估计指的是 Diablo但放在前端语境里不管大菠萝还是小菠萝能帮我们把组件之间共享的状态管好那就是好菠萝。这篇内容不打算绕弯子我把这几年用 Pinia 的实际经验、踩过的坑、还有从 Vuex 迁移过来的心路历程都整理出来。不管你是刚接触 Vue 的新人还是准备从 Vuex 换到 Pinia 的老手这篇都能给你一个比较完整的参考。尤其要说明白一件事为什么大家都说 Pinia 好它到底好在哪里以及你上手之后最容易在哪些地方翻车。1. 为什么选择 Pinia从 Vuex 手里接过接力棒1.1 从 Vuex 到 Pinia那些年被吐槽的痛聊 Pinia 之前得先看看 Vuex 当年被吐槽的点。Vuex 是 Vue 2 时代的标准答案但用久了大家心里都憋着火。第一个痛点是 mutations 的仪式感。Vuex 要求修改状态必须走commit(mutationName)然后 mutation 里再同步修改 state。异步逻辑要放进 actions由 action 去 commit mutation。这个流程本身是出于可追踪性考虑但实际项目里大量样板代码的产生都源于这个设计。我见过不少团队写着写着就发明了“直接改 state”的土办法因为它太啰嗦了。第二个痛点是 TypeScript 支持。Vuex 的 TS 类型推导一直别扭尤其是模块嵌套之后this.$store.state.moduleA.moduleB这种深层次取数类型经常是 any 或者需要大量手写类型声明很难受。第三个痛点是模块化设计。Vuex 的 modules 有命名空间的概念子模块的 state、getters、mutations、actions 都挂在一个大树上取名要带前缀路径很长。多人协作时经常因为 module 名的层级嵌套而争论读代码的心智负担很重。Pinia 的出现本质上是对这些痛点的一次外科手术式拆除。它没有 mutations没有 module 嵌套store 是扁平化的整个 API 精简到三个核心概念state、getters、actions。而且它是为 Composition API 量身定制的写起来就像在写一段普通的 JS 逻辑而不是在跟框架做斗争。1.2 Pinia 的设计理念少即是多扁平即自由Pinia 的核心设计理念一句话概括就是“状态就是普通的响应式对象”。它不搞黑魔法不搞复杂的中间层。你定义一个 store本质上是把一堆属性和方法组织在一起形成一个独立的逻辑单元。在 Pinia 里每个 store 就是一个defineStore调用的产物。它天然是扁平的没有命名空间的前缀问题。但扁平不代表会命名冲突因为每个 store 必须有一个全局唯一 id比如defineStore(cart, ...)里的cart。这个 id 既用作 devtools 里的标识也用作 store 之间的依赖引用所以只要 id 不冲突就行store 之间不需要嵌套。从 Vuex 迁移到 Pinia最直观的感受是写起来更像“正常代码”。定义 state 就是一个ref或reactive定义 getters 就是一个computed定义 actions 就是一个普通函数。这跟 Vue Composition API 的心智模型完全一致上手成本几乎为零。很多人说 Pinia 是“Vuex 5 的雏形”其实更准确的说法是Pinia 回归了状态管理的本质——它就是一组响应式数据和操作这些数据的函数的集合。2. 核心概念拆解小菠萝的三种风味与关键 API2.1 Option Store 与 Setup Store两种风格怎么选Pinia 提供了两种定义 store 的写法这是很多新手第一次接触时的疑问点。Option Store 的写法比较像 Vuex。看代码最直观// stores/counter.ts import { defineStore } from pinia export const useCounterStore defineStore(counter, { state: () ({ count: 0, name: 菠萝, }), getters: { doubleCount: (state) state.count * 2, }, actions: { increment() { this.count }, }, })这种写法的好处是结构固定state、getters、actions 各就各位一眼就能看出这个 store 里有什么状态、什么计算属性、什么操作。对从 Vuex 迁移过来的项目来说这种写法的迁移成本最低。Setup Store 的写法则更像是把 Composition API 搬进来import { ref, computed } from vue import { defineStore } from pinia export const useCounterStore defineStore(counter, () { const count ref(0) const name ref(菠萝) const doubleCount computed(() count.value * 2) function increment() { count.value } return { count, name, doubleCount, increment } })Setup Store 的写法给了我一种自由感。复杂逻辑可以直接在 store 内部通过拆分函数来组织比如把取数据的逻辑抽成一个私有函数再在 action 里调用。这种写法对代码重构更友好也更容易利用 Composition API 的特性比如watch、生命周期钩子。我的建议是新项目优先用 Setup Store因为它更灵活老项目从 Vuex 迁移过来可以用 Option Store 过渡等熟悉之后再慢慢改造成 Setup Store。两种风格可以混用Pinia 不强迫你只能选一种这在团队协作时可以逐步推进而不是一夜重写。2.2 state、getters、actions三件套的细节与坑先聊 state。state 在组件里可以直接修改这是 Pinia 和 Vuex 最大的区别。你可以直接写store.count或者调用store.$patch({ count: 1 })。相比 Vuex少了一层 commit 的过程。但自由也带来了责任我在代码审查时见过有人把业务计算逻辑一股脑写进组件里直接临时计算 state这就是在滥用“直接修改”的能力了。该进 getters 的进 getters该进 actions 的进 actions否则状态管理很快会变成一锅粥。getters 本质上就是计算属性。它支持直接访问 thisgetters: { countWithSuffix(): string { return ${this.count} 个菠萝 }, }getters 之间还可以互相调用比如doubleCount引用countWithSuffix去拼字符串。但要注意不要在 getters 里做有副作用的事情比如修改 state 或发请求。我见过有人把异步请求写进 getters导致页面反复刷新时请求被无限触发这是所有新手都容易踩进去的坑。actions 是放业务逻辑的地方。异步请求、调接口、组合多个 store 的操作都放进 actions。在 actions 里访问 store 实例用this返回一个 Promise组件里就能await store.fetchData()了。$patch也是一个高频 API。它接收一个对象或一个函数适合批量更新多个字段。store.$patch((state) { state.items.push(newItem) state.total state.items.length })注意一点如果你用Object.assign给 store 整体赋值那大概率会丢响应式。但用$patch就不会它内部帮你处理好了响应式更新。这是官方推荐的批量更新方式。2.3 关于 storeToRefs小心解构后变成“死数据”我在带新人时几乎每两周就会遇到一次“解构后响应式丢失”的问题。比如在组件里想当然这样写script setup langts import { useCounterStore } from /stores/counter const store useCounterStore() const { count, doubleCount } store /script结果页面上count变成了一个一次性快照点击按钮后页面不会更新。原因很简单Pinia 的 store 是用reactive包裹的解构出来的基础类型值不会保持响应式链接。解决办法是使用官方提供的storeToRefsscript setup langts import { storeToRefs } from pinia import { useCounterStore } from /stores/counter const store useCounterStore() const { count, doubleCount } storeToRefs(store) /script需要注意的是storeToRefs只处理 state 和 getters不要拿来解构 actions。actions 本来就是普通函数直接const { increment } store解构就行没有响应式要求。如果你用storeToRefs去解构 actions它不会给你函数会直接报错或返回 undefined。这个细节在实际开发里很常见值得留意。3. 购物车实战从头搭一个“菠萝超市”项目3.1 项目初始化与依赖安装我准备用一个购物车的例子来串一遍完整的实操流程因为购物车这个场景几乎覆盖了状态管理的大多数基本功列表数据、增删改、计算总价、跨组件共享。假设你已经用 Vite 创建好了一个 Vue 3 TypeScript 项目。安装依赖很简单npm install pinia然后在入口文件里注册// main.ts 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()要尽早注册最好是在app.use()阶段完成。因为 store 只有在 Pinia 实例激活后才能被调用如果某个模块在注册前就执行了useCartStore()会报一个getActivePinia()的错误。这种情况在 SSR 或者一些路由懒加载场景下比较常见后面排查章节会细说。3.2 定义商品列表与购物车两个 store我先定义商品列表 store。实战中商品数据通常来自后端接口这里用 mock 数组重点看结构// stores/products.ts import { defineStore } from pinia export interface Product { id: number name: string price: number stock: number } export const useProductsStore defineStore(products, { state: () ({ products: [] as Product[], loading: false, }), getters: { totalCount: (state) state.products.length, }, actions: { async fetchProducts() { this.loading true try { // 实际开发中替换为 axios 或 fetch 请求 const res await new PromiseProduct[]((resolve) { setTimeout(() { resolve([ { id: 1, name: 小菠萝抱枕, price: 29.9, stock: 10 }, { id: 2, name: 大菠萝公仔, price: 49.9, stock: 5 }, { id: 3, name: 菠萝汽水, price: 6.9, stock: 100 }, ]) }, 500) }) this.products res } finally { this.loading false } }, }, })接下来是购物车 store。这里我用了 Setup Store 的写法两者可以对比看看。购物车需要维护购物项、数量、总价同时还要和商品库存联动// stores/cart.ts import { ref, computed } from vue import { defineStore } from pinia import { useProductsStore } from ./products export interface CartItem { productId: number name: string price: number quantity: number } export const useCartStore defineStore(cart, () { const items refCartItem[]([]) const totalQuantity computed(() items.value.reduce((sum, item) sum item.quantity, 0) ) const totalPrice computed(() items.value.reduce((sum, item) sum item.price * item.quantity, 0) ) function addItem(productId: number, quantity 1) { const productsStore useProductsStore() const product productsStore.products.find((item) item.id productId) if (!product) return if (product.stock quantity) { console.warn(库存不足${product.name} 只剩 ${product.stock} 件) return } const existingItem items.value.find((item) item.productId productId) if (existingItem) { existingItem.quantity quantity } else { items.value.push({ productId: product.id, name: product.name, price: product.price, quantity, }) } } function removeItem(productId: number) { items.value items.value.filter((item) item.productId ! productId) } function clearCart() { items.value [] } return { items, totalQuantity, totalPrice, addItem, removeItem, clearCart, } })注意这段代码里addItemaction 内通过useProductsStore()读取了另一个 store 的 state这就是 Pinia 跨 store 协作的典型用法。不需要引入什么特殊概念直接在一个 action 里调用另一个 store 的 hook 即可。3.3 在 Vue 组件中接入两类 store商品列表组件负责展示商品和“加入购物车”按钮!-- components/ProductList.vue -- script setup langts import { onMounted } from vue import { storeToRefs } from pinia import { useProductsStore } from /stores/products import { useCartStore } from /stores/cart const productsStore useProductsStore() const cartStore useCartStore() const { products, loading } storeToRefs(productsStore) onMounted(() { productsStore.fetchProducts() }) function handleAdd(productId: number) { cartStore.addItem(productId, 1) } /script template div v-ifloading加载中.../div div v-else div v-forproduct in products :keyproduct.id classproduct-card h3{{ product.name }}/h3 p价格{{ product.price }} 元/p p库存{{ product.stock }} 件/p button :disabledproduct.stock 0 clickhandleAdd(product.id) 加入购物车 /button /div /div /template购物车面板组件负责展示总价和商品数量!-- components/CartPanel.vue -- script setup langts import { storeToRefs } from pinia import { useCartStore } from /stores/cart const cartStore useCartStore() const { items, totalQuantity, totalPrice } storeToRefs(cartStore) /script template div classcart-panel h2购物车{{ totalQuantity }}/h2 div v-foritem in items :keyitem.productId classcart-item span{{ item.name }}/span span{{ item.quantity }} 件/span span{{ item.price * item.quantity }} 元/span button clickcartStore.removeItem(item.productId)移除/button /div p总计{{ totalPrice }} 元/p button clickcartStore.clearCart()清空购物车/button /div /template然后 App.vue 里左右排布就完成了。这个例子虽然小但把 Pinia 的“跨组件共享 跨 store 调用 异步 action 计算属性”都串起来了。完成之后“加入购物车”按钮的操作会同时反映在购物车列表、总数量、总价上完全不需要任何事件总线或 props 层层传递。3.4 v-model 与 store 联动的写法另一个经常会遇到的需求是表单输入框直接绑定 store 里的字段。比如一个搜索关键词或者一个用户配置项。最直观的写法是input v-modelstore.keyword /这确实可以工作。但如果你想拆出来用storeToRefs获取字段直接对ref用v-model就不行了因为storeToRefs返回的是只读 refgetter 层面。常见的做法是给这个 ref 包一层 computedscript setup langts import { computed } from vue import { storeToRefs } from pinia import { useSearchStore } from /stores/search const searchStore useSearchStore() const { keyword } storeToRefs(searchStore) const keywordModel computed({ get: () keyword.value, set: (val: string) { searchStore.keyword val }, }) /script template input v-modelkeywordModel placeholder搜索菠萝 / /template这样既保持了响应式又可以精确控制 setter 副作用比如自动触发搜索防抖。真实项目中这个模式非常常用建议直接收藏。4. 多人协作与项目组织store 文件怎么规划才不乱4.1 大型项目里 store 拆分的两种策略很多新手在小项目里把购物车、用户信息、订单全部塞进一个 store 文件刚开始没问题等需求迭代几轮之后文件轻松破千行改一个字段还要担心影响其他模块。这里我给出两个常见的拆分策略。第一个策略是按领域拆。每个业务领域一个 store例如stores/user.ts、stores/order.ts、stores/cart.ts、stores/product.ts。这个策略适合业务边界清晰的后台管理系统、商城系统。主要看“领域”的划分是否符合产品功能分区。第二个策略是按页面或组件拆。每个路由页面一个 store例如stores/checkout.ts管结算页的所有状态stores/productDetail.ts管商品详情页的数据。这个策略适合强交互的单页应用因为页面级状态往往跟路由生命周期绑定。我的建议是不要一开始就追求“完美拆分”。只要每个 store 能说清楚“这个 store 管的是什么”就先拆出来等这个 store 的功能量变大之后再往下细分。拆分的判断标准是看这个 store 是否出现了“两个不相关的操作经常需要同时修改但逻辑上不关联的字段”如果是就说明它应该拆了。我自己习惯把 store 文件统一放在src/stores/目录下文件名小写中划线每个文件默认导出一个useXxxStore函数。这个命名规范在项目里固定下来团队协作时搜索起来很方便。4.2 Setup Store 内部的模块化技巧Setup Store 写复杂了之后store 内部也会变得臃肿。一个很实用的技巧是把复杂的业务逻辑抽到独立的可复用函数里而不是都堆在回调函数里。有人把这种做法叫 “composable store”。以用户 store 为例// stores/user.ts import { ref, computed } from vue import { defineStore } from pinia import { fetchUserProfile, updateUserProfile } from /api/user import type { UserProfile } from /types/user export const useUserStore defineStore(user, () { const profile refUserProfile | null(null) const token ref() const isLoggedIn computed(() !!token.value) async function login(username: string, password: string) { // 省略具体登录逻辑 const res await fetchUserProfile(username, password) token.value res.token profile.value res.profile } async function refreshProfile() { if (!token.value) return profile.value await fetchUserProfile() } async function updateProfile(patch: PartialUserProfile) { profile.value await updateUserProfile(patch) } return { profile, token, isLoggedIn, login, refreshProfile, updateProfile } })可以看到API 调用被封装在 store 的 action 里组件只需要调用store.login()或store.refreshProfile()不用关心请求细节。如果后续要加缓存、重试、错误上报只需要在 action 内部做改动组件层完全不用动。这就把“业务逻辑”和“视图”彻底解耦了。另外Setup Store 内部可以写很多私有函数。比如状态初始化时的默认值函数、字段格式化函数都可以定义在 return 之前不暴露给外部。这样调试时看到 store 实例暴露出来的属性都是干净的。4.3 store 之间循环引用的规避实践Pinia 允许在 action 里调用另一个 store 的 hook这在前面购物车例子里已经体现。但项目一大容易出现两个 store 互相依赖的情况。比如 A 的 action 里调用了 useBStoreB 的 action 里又调用了 useAStore。如果是在函数体内调用 hook通常因为懒执行而不会出问题但如果是在 store 定义阶段就调用就可能遇到初始化顺序的问题。最安全的做法是在主 store 模块中import另一个 store 的useXxxStore时只在函数体内调用而不是在模块顶层或 setup 顶层调用。同时注意命名不要循环引用。举个例子// stores/order.ts import { defineStore } from pinia import { useCartStore } from ./cart export const useOrderStore defineStore(order, () { function checkout() { const cartStore useCartStore() const items cartStore.items.map(...) // 下单逻辑 cartStore.clearCart() } return { checkout } })这段代码把useCartStore()放在checkout函数里面调用而不是在defineStore的回调顶层调用。这样可以避免在 order store 初始化时就去实例化 cart store万一碰到循环引用也不容易出现 “Cannot access before initialization” 的问题。5. 常见问题与排查技巧实录5.1 遇到的报错与解决方案速查表这一节把我觉得最有代表性的几个问题整理成表方便大家直接对照。问题现象报错/表现原因解决方案调用 store 时报错getActivePinia was called but there was no active Pinia写在 app.use(pinia) 之前或 SSR 场景未传 pinia 实例在入口注册 pinia必要时显式传入setup或useStore(pinia)解构后无响应式页面不更新控制台无报错直接解构reactive包裹的 store用storeToRefs包裹 state/getters响应式变成普通对象数组/对象更新后视图不刷新用整体替换 state 中的引用类型优先用$patch或直接修改属性store 名称冲突运行时 console 警告或状态串了两个 store 使用了相同 id确保 id 全局唯一文件重命名时注意修改 store 数据但 devtools 看不到未开启 devtools 或使用了不同 Pinia 实例插件未安装或入口注册了多次只在入口注册一次 createPinia5.2 排查响应式丢失一个真实案例我带团队时有个同事做表单页把表单字段全部用storeToRefs解构到组件里然后给输入框绑定了v-model。结果发现输入的时候页面闪一下但是 store 里的值没有变化。后来排查发现他把一个带 setter 的 getter 直接解构出来赋值给 v-model但storeToRefs返回的 computed ref 默认是不允许直接赋值的所以每次输入都触发了 Vue 的“写操作失败”提示。这种情况下正确做法是手工包一个computed({ get: () store.field, set: (v) store.setField(v) })。这个案例告诉我们不是任何状态都适合直接解构需要区分“纯展示值”和“可写值”。纯展示值用storeToRefs很安全可写值建议直接通过store.xxx ...来赋值或者提供对应的 action/setter。5.3 devtools 调试与性能小贴士Pinia 对 Vue Devtools 的支持很好安装好 Pinia 插件后在 devtools 里可以直接查看每个 store 的 state、getters、actions 调用记录还能时光旅行。实际调试中我常用的是 devtools 里的 Pinia 面板可以直接修改 state 值来调试组件行为不需要改代码。而且它会把每次 action 调用记录为时间线里的事件便于追踪“用户先点了什么然后状态变成了什么”。性能方面有一个容易忽略的点如果 getters 返回的是新对象或执行了复杂计算每次访问都会重新计算。这时候可以用 computed 缓存但要确保内部的依赖是响应式的。比如const productOptions computed(() products.value.map((product) ({ label: product.name, value: product.id })) )这样productOptions只有在products变化时才会重新计算。不要把它写成普通函数否则每次渲染都会重新执行一遍。另外如果 store 中有大量的列表数据显示建议在渲染层配合v-memo或者组件的defineProps对比控制重新渲染范围避免所有引用了 store 的组件在任意 state 变更时都重新渲染。Pinia 不像 Vuex 那样按模块订阅而是所有引用 store 的组件都会响应 store 内任何变化所以性能优化要靠开发者自己控制这一点容易被忽略。最后分享一个习惯我写 action 时会在关键的参数校验失败或请求失败时在代码里直接抛异常或console.warn而不是让每个组件都静默失败。这样一来问题迟早会在开发期暴露出来而不是等到线上才由用户发现。这个小习惯帮我们团队减少了非常多定位问题的时间。Pinia 这个库本身不复杂复杂的是怎么用好它。希望这篇能帮你少走一些弯路。 
长河君 · 2026/9/10 5:28:49 · 阅读 1.2k Pinia状态管理实战：从Vuex迁移到菠萝时代
看到“5. pinia 小菠萝大菠萝都是菠萝”这个项目标题我第一反应是这兄弟是在写绕口令还是在给前端状态管理库起花名点进去一看果然是在说 Pinia。对 Vue 开发者来说pinia 这个词已经不陌生了它就是 Vue 官方钦定的下一代状态管理库。名字里带个“pinia”其实是菠萝pineapple的词根所以大家习惯叫它“小菠萝”。标题里的“大菠萝”估计指的是 Diablo但放在前端语境里不管大菠萝还是小菠萝能帮我们把组件之间共享的状态管好那就是好菠萝。这篇内容不打算绕弯子我把这几年用 Pinia 的实际经验、踩过的坑、还有从 Vuex 迁移过来的心路历程都整理出来。不管你是刚接触 Vue 的新人还是准备从 Vuex 换到 Pinia 的老手这篇都能给你一个比较完整的参考。尤其要说明白一件事为什么大家都说 Pinia 好它到底好在哪里以及你上手之后最容易在哪些地方翻车。1. 为什么选择 Pinia从 Vuex 手里接过接力棒1.1 从 Vuex 到 Pinia那些年被吐槽的痛聊 Pinia 之前得先看看 Vuex 当年被吐槽的点。Vuex 是 Vue 2 时代的标准答案但用久了大家心里都憋着火。第一个痛点是 mutations 的仪式感。Vuex 要求修改状态必须走commit(mutationName)然后 mutation 里再同步修改 state。异步逻辑要放进 actions由 action 去 commit mutation。这个流程本身是出于可追踪性考虑但实际项目里大量样板代码的产生都源于这个设计。我见过不少团队写着写着就发明了“直接改 state”的土办法因为它太啰嗦了。第二个痛点是 TypeScript 支持。Vuex 的 TS 类型推导一直别扭尤其是模块嵌套之后this.$store.state.moduleA.moduleB这种深层次取数类型经常是 any 或者需要大量手写类型声明很难受。第三个痛点是模块化设计。Vuex 的 modules 有命名空间的概念子模块的 state、getters、mutations、actions 都挂在一个大树上取名要带前缀路径很长。多人协作时经常因为 module 名的层级嵌套而争论读代码的心智负担很重。Pinia 的出现本质上是对这些痛点的一次外科手术式拆除。它没有 mutations没有 module 嵌套store 是扁平化的整个 API 精简到三个核心概念state、getters、actions。而且它是为 Composition API 量身定制的写起来就像在写一段普通的 JS 逻辑而不是在跟框架做斗争。1.2 Pinia 的设计理念少即是多扁平即自由Pinia 的核心设计理念一句话概括就是“状态就是普通的响应式对象”。它不搞黑魔法不搞复杂的中间层。你定义一个 store本质上是把一堆属性和方法组织在一起形成一个独立的逻辑单元。在 Pinia 里每个 store 就是一个defineStore调用的产物。它天然是扁平的没有命名空间的前缀问题。但扁平不代表会命名冲突因为每个 store 必须有一个全局唯一 id比如defineStore(cart, ...)里的cart。这个 id 既用作 devtools 里的标识也用作 store 之间的依赖引用所以只要 id 不冲突就行store 之间不需要嵌套。从 Vuex 迁移到 Pinia最直观的感受是写起来更像“正常代码”。定义 state 就是一个ref或reactive定义 getters 就是一个computed定义 actions 就是一个普通函数。这跟 Vue Composition API 的心智模型完全一致上手成本几乎为零。很多人说 Pinia 是“Vuex 5 的雏形”其实更准确的说法是Pinia 回归了状态管理的本质——它就是一组响应式数据和操作这些数据的函数的集合。2. 核心概念拆解小菠萝的三种风味与关键 API2.1 Option Store 与 Setup Store两种风格怎么选Pinia 提供了两种定义 store 的写法这是很多新手第一次接触时的疑问点。Option Store 的写法比较像 Vuex。看代码最直观// stores/counter.ts import { defineStore } from pinia export const useCounterStore defineStore(counter, { state: () ({ count: 0, name: 菠萝, }), getters: { doubleCount: (state) state.count * 2, }, actions: { increment() { this.count }, }, })这种写法的好处是结构固定state、getters、actions 各就各位一眼就能看出这个 store 里有什么状态、什么计算属性、什么操作。对从 Vuex 迁移过来的项目来说这种写法的迁移成本最低。Setup Store 的写法则更像是把 Composition API 搬进来import { ref, computed } from vue import { defineStore } from pinia export const useCounterStore defineStore(counter, () { const count ref(0) const name ref(菠萝) const doubleCount computed(() count.value * 2) function increment() { count.value } return { count, name, doubleCount, increment } })Setup Store 的写法给了我一种自由感。复杂逻辑可以直接在 store 内部通过拆分函数来组织比如把取数据的逻辑抽成一个私有函数再在 action 里调用。这种写法对代码重构更友好也更容易利用 Composition API 的特性比如watch、生命周期钩子。我的建议是新项目优先用 Setup Store因为它更灵活老项目从 Vuex 迁移过来可以用 Option Store 过渡等熟悉之后再慢慢改造成 Setup Store。两种风格可以混用Pinia 不强迫你只能选一种这在团队协作时可以逐步推进而不是一夜重写。2.2 state、getters、actions三件套的细节与坑先聊 state。state 在组件里可以直接修改这是 Pinia 和 Vuex 最大的区别。你可以直接写store.count或者调用store.$patch({ count: 1 })。相比 Vuex少了一层 commit 的过程。但自由也带来了责任我在代码审查时见过有人把业务计算逻辑一股脑写进组件里直接临时计算 state这就是在滥用“直接修改”的能力了。该进 getters 的进 getters该进 actions 的进 actions否则状态管理很快会变成一锅粥。getters 本质上就是计算属性。它支持直接访问 thisgetters: { countWithSuffix(): string { return ${this.count} 个菠萝 }, }getters 之间还可以互相调用比如doubleCount引用countWithSuffix去拼字符串。但要注意不要在 getters 里做有副作用的事情比如修改 state 或发请求。我见过有人把异步请求写进 getters导致页面反复刷新时请求被无限触发这是所有新手都容易踩进去的坑。actions 是放业务逻辑的地方。异步请求、调接口、组合多个 store 的操作都放进 actions。在 actions 里访问 store 实例用this返回一个 Promise组件里就能await store.fetchData()了。$patch也是一个高频 API。它接收一个对象或一个函数适合批量更新多个字段。store.$patch((state) { state.items.push(newItem) state.total state.items.length })注意一点如果你用Object.assign给 store 整体赋值那大概率会丢响应式。但用$patch就不会它内部帮你处理好了响应式更新。这是官方推荐的批量更新方式。2.3 关于 storeToRefs小心解构后变成“死数据”我在带新人时几乎每两周就会遇到一次“解构后响应式丢失”的问题。比如在组件里想当然这样写script setup langts import { useCounterStore } from /stores/counter const store useCounterStore() const { count, doubleCount } store /script结果页面上count变成了一个一次性快照点击按钮后页面不会更新。原因很简单Pinia 的 store 是用reactive包裹的解构出来的基础类型值不会保持响应式链接。解决办法是使用官方提供的storeToRefsscript setup langts import { storeToRefs } from pinia import { useCounterStore } from /stores/counter const store useCounterStore() const { count, doubleCount } storeToRefs(store) /script需要注意的是storeToRefs只处理 state 和 getters不要拿来解构 actions。actions 本来就是普通函数直接const { increment } store解构就行没有响应式要求。如果你用storeToRefs去解构 actions它不会给你函数会直接报错或返回 undefined。这个细节在实际开发里很常见值得留意。3. 购物车实战从头搭一个“菠萝超市”项目3.1 项目初始化与依赖安装我准备用一个购物车的例子来串一遍完整的实操流程因为购物车这个场景几乎覆盖了状态管理的大多数基本功列表数据、增删改、计算总价、跨组件共享。假设你已经用 Vite 创建好了一个 Vue 3 TypeScript 项目。安装依赖很简单npm install pinia然后在入口文件里注册// main.ts 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()要尽早注册最好是在app.use()阶段完成。因为 store 只有在 Pinia 实例激活后才能被调用如果某个模块在注册前就执行了useCartStore()会报一个getActivePinia()的错误。这种情况在 SSR 或者一些路由懒加载场景下比较常见后面排查章节会细说。3.2 定义商品列表与购物车两个 store我先定义商品列表 store。实战中商品数据通常来自后端接口这里用 mock 数组重点看结构// stores/products.ts import { defineStore } from pinia export interface Product { id: number name: string price: number stock: number } export const useProductsStore defineStore(products, { state: () ({ products: [] as Product[], loading: false, }), getters: { totalCount: (state) state.products.length, }, actions: { async fetchProducts() { this.loading true try { // 实际开发中替换为 axios 或 fetch 请求 const res await new PromiseProduct[]((resolve) { setTimeout(() { resolve([ { id: 1, name: 小菠萝抱枕, price: 29.9, stock: 10 }, { id: 2, name: 大菠萝公仔, price: 49.9, stock: 5 }, { id: 3, name: 菠萝汽水, price: 6.9, stock: 100 }, ]) }, 500) }) this.products res } finally { this.loading false } }, }, })接下来是购物车 store。这里我用了 Setup Store 的写法两者可以对比看看。购物车需要维护购物项、数量、总价同时还要和商品库存联动// stores/cart.ts import { ref, computed } from vue import { defineStore } from pinia import { useProductsStore } from ./products export interface CartItem { productId: number name: string price: number quantity: number } export const useCartStore defineStore(cart, () { const items refCartItem[]([]) const totalQuantity computed(() items.value.reduce((sum, item) sum item.quantity, 0) ) const totalPrice computed(() items.value.reduce((sum, item) sum item.price * item.quantity, 0) ) function addItem(productId: number, quantity 1) { const productsStore useProductsStore() const product productsStore.products.find((item) item.id productId) if (!product) return if (product.stock quantity) { console.warn(库存不足${product.name} 只剩 ${product.stock} 件) return } const existingItem items.value.find((item) item.productId productId) if (existingItem) { existingItem.quantity quantity } else { items.value.push({ productId: product.id, name: product.name, price: product.price, quantity, }) } } function removeItem(productId: number) { items.value items.value.filter((item) item.productId ! productId) } function clearCart() { items.value [] } return { items, totalQuantity, totalPrice, addItem, removeItem, clearCart, } })注意这段代码里addItemaction 内通过useProductsStore()读取了另一个 store 的 state这就是 Pinia 跨 store 协作的典型用法。不需要引入什么特殊概念直接在一个 action 里调用另一个 store 的 hook 即可。3.3 在 Vue 组件中接入两类 store商品列表组件负责展示商品和“加入购物车”按钮!-- components/ProductList.vue -- script setup langts import { onMounted } from vue import { storeToRefs } from pinia import { useProductsStore } from /stores/products import { useCartStore } from /stores/cart const productsStore useProductsStore() const cartStore useCartStore() const { products, loading } storeToRefs(productsStore) onMounted(() { productsStore.fetchProducts() }) function handleAdd(productId: number) { cartStore.addItem(productId, 1) } /script template div v-ifloading加载中.../div div v-else div v-forproduct in products :keyproduct.id classproduct-card h3{{ product.name }}/h3 p价格{{ product.price }} 元/p p库存{{ product.stock }} 件/p button :disabledproduct.stock 0 clickhandleAdd(product.id) 加入购物车 /button /div /div /template购物车面板组件负责展示总价和商品数量!-- components/CartPanel.vue -- script setup langts import { storeToRefs } from pinia import { useCartStore } from /stores/cart const cartStore useCartStore() const { items, totalQuantity, totalPrice } storeToRefs(cartStore) /script template div classcart-panel h2购物车{{ totalQuantity }}/h2 div v-foritem in items :keyitem.productId classcart-item span{{ item.name }}/span span{{ item.quantity }} 件/span span{{ item.price * item.quantity }} 元/span button clickcartStore.removeItem(item.productId)移除/button /div p总计{{ totalPrice }} 元/p button clickcartStore.clearCart()清空购物车/button /div /template然后 App.vue 里左右排布就完成了。这个例子虽然小但把 Pinia 的“跨组件共享 跨 store 调用 异步 action 计算属性”都串起来了。完成之后“加入购物车”按钮的操作会同时反映在购物车列表、总数量、总价上完全不需要任何事件总线或 props 层层传递。3.4 v-model 与 store 联动的写法另一个经常会遇到的需求是表单输入框直接绑定 store 里的字段。比如一个搜索关键词或者一个用户配置项。最直观的写法是input v-modelstore.keyword /这确实可以工作。但如果你想拆出来用storeToRefs获取字段直接对ref用v-model就不行了因为storeToRefs返回的是只读 refgetter 层面。常见的做法是给这个 ref 包一层 computedscript setup langts import { computed } from vue import { storeToRefs } from pinia import { useSearchStore } from /stores/search const searchStore useSearchStore() const { keyword } storeToRefs(searchStore) const keywordModel computed({ get: () keyword.value, set: (val: string) { searchStore.keyword val }, }) /script template input v-modelkeywordModel placeholder搜索菠萝 / /template这样既保持了响应式又可以精确控制 setter 副作用比如自动触发搜索防抖。真实项目中这个模式非常常用建议直接收藏。4. 多人协作与项目组织store 文件怎么规划才不乱4.1 大型项目里 store 拆分的两种策略很多新手在小项目里把购物车、用户信息、订单全部塞进一个 store 文件刚开始没问题等需求迭代几轮之后文件轻松破千行改一个字段还要担心影响其他模块。这里我给出两个常见的拆分策略。第一个策略是按领域拆。每个业务领域一个 store例如stores/user.ts、stores/order.ts、stores/cart.ts、stores/product.ts。这个策略适合业务边界清晰的后台管理系统、商城系统。主要看“领域”的划分是否符合产品功能分区。第二个策略是按页面或组件拆。每个路由页面一个 store例如stores/checkout.ts管结算页的所有状态stores/productDetail.ts管商品详情页的数据。这个策略适合强交互的单页应用因为页面级状态往往跟路由生命周期绑定。我的建议是不要一开始就追求“完美拆分”。只要每个 store 能说清楚“这个 store 管的是什么”就先拆出来等这个 store 的功能量变大之后再往下细分。拆分的判断标准是看这个 store 是否出现了“两个不相关的操作经常需要同时修改但逻辑上不关联的字段”如果是就说明它应该拆了。我自己习惯把 store 文件统一放在src/stores/目录下文件名小写中划线每个文件默认导出一个useXxxStore函数。这个命名规范在项目里固定下来团队协作时搜索起来很方便。4.2 Setup Store 内部的模块化技巧Setup Store 写复杂了之后store 内部也会变得臃肿。一个很实用的技巧是把复杂的业务逻辑抽到独立的可复用函数里而不是都堆在回调函数里。有人把这种做法叫 “composable store”。以用户 store 为例// stores/user.ts import { ref, computed } from vue import { defineStore } from pinia import { fetchUserProfile, updateUserProfile } from /api/user import type { UserProfile } from /types/user export const useUserStore defineStore(user, () { const profile refUserProfile | null(null) const token ref() const isLoggedIn computed(() !!token.value) async function login(username: string, password: string) { // 省略具体登录逻辑 const res await fetchUserProfile(username, password) token.value res.token profile.value res.profile } async function refreshProfile() { if (!token.value) return profile.value await fetchUserProfile() } async function updateProfile(patch: PartialUserProfile) { profile.value await updateUserProfile(patch) } return { profile, token, isLoggedIn, login, refreshProfile, updateProfile } })可以看到API 调用被封装在 store 的 action 里组件只需要调用store.login()或store.refreshProfile()不用关心请求细节。如果后续要加缓存、重试、错误上报只需要在 action 内部做改动组件层完全不用动。这就把“业务逻辑”和“视图”彻底解耦了。另外Setup Store 内部可以写很多私有函数。比如状态初始化时的默认值函数、字段格式化函数都可以定义在 return 之前不暴露给外部。这样调试时看到 store 实例暴露出来的属性都是干净的。4.3 store 之间循环引用的规避实践Pinia 允许在 action 里调用另一个 store 的 hook这在前面购物车例子里已经体现。但项目一大容易出现两个 store 互相依赖的情况。比如 A 的 action 里调用了 useBStoreB 的 action 里又调用了 useAStore。如果是在函数体内调用 hook通常因为懒执行而不会出问题但如果是在 store 定义阶段就调用就可能遇到初始化顺序的问题。最安全的做法是在主 store 模块中import另一个 store 的useXxxStore时只在函数体内调用而不是在模块顶层或 setup 顶层调用。同时注意命名不要循环引用。举个例子// stores/order.ts import { defineStore } from pinia import { useCartStore } from ./cart export const useOrderStore defineStore(order, () { function checkout() { const cartStore useCartStore() const items cartStore.items.map(...) // 下单逻辑 cartStore.clearCart() } return { checkout } })这段代码把useCartStore()放在checkout函数里面调用而不是在defineStore的回调顶层调用。这样可以避免在 order store 初始化时就去实例化 cart store万一碰到循环引用也不容易出现 “Cannot access before initialization” 的问题。5. 常见问题与排查技巧实录5.1 遇到的报错与解决方案速查表这一节把我觉得最有代表性的几个问题整理成表方便大家直接对照。问题现象报错/表现原因解决方案调用 store 时报错getActivePinia was called but there was no active Pinia写在 app.use(pinia) 之前或 SSR 场景未传 pinia 实例在入口注册 pinia必要时显式传入setup或useStore(pinia)解构后无响应式页面不更新控制台无报错直接解构reactive包裹的 store用storeToRefs包裹 state/getters响应式变成普通对象数组/对象更新后视图不刷新用整体替换 state 中的引用类型优先用$patch或直接修改属性store 名称冲突运行时 console 警告或状态串了两个 store 使用了相同 id确保 id 全局唯一文件重命名时注意修改 store 数据但 devtools 看不到未开启 devtools 或使用了不同 Pinia 实例插件未安装或入口注册了多次只在入口注册一次 createPinia5.2 排查响应式丢失一个真实案例我带团队时有个同事做表单页把表单字段全部用storeToRefs解构到组件里然后给输入框绑定了v-model。结果发现输入的时候页面闪一下但是 store 里的值没有变化。后来排查发现他把一个带 setter 的 getter 直接解构出来赋值给 v-model但storeToRefs返回的 computed ref 默认是不允许直接赋值的所以每次输入都触发了 Vue 的“写操作失败”提示。这种情况下正确做法是手工包一个computed({ get: () store.field, set: (v) store.setField(v) })。这个案例告诉我们不是任何状态都适合直接解构需要区分“纯展示值”和“可写值”。纯展示值用storeToRefs很安全可写值建议直接通过store.xxx ...来赋值或者提供对应的 action/setter。5.3 devtools 调试与性能小贴士Pinia 对 Vue Devtools 的支持很好安装好 Pinia 插件后在 devtools 里可以直接查看每个 store 的 state、getters、actions 调用记录还能时光旅行。实际调试中我常用的是 devtools 里的 Pinia 面板可以直接修改 state 值来调试组件行为不需要改代码。而且它会把每次 action 调用记录为时间线里的事件便于追踪“用户先点了什么然后状态变成了什么”。性能方面有一个容易忽略的点如果 getters 返回的是新对象或执行了复杂计算每次访问都会重新计算。这时候可以用 computed 缓存但要确保内部的依赖是响应式的。比如const productOptions computed(() products.value.map((product) ({ label: product.name, value: product.id })) )这样productOptions只有在products变化时才会重新计算。不要把它写成普通函数否则每次渲染都会重新执行一遍。另外如果 store 中有大量的列表数据显示建议在渲染层配合v-memo或者组件的defineProps对比控制重新渲染范围避免所有引用了 store 的组件在任意 state 变更时都重新渲染。Pinia 不像 Vuex 那样按模块订阅而是所有引用 store 的组件都会响应 store 内任何变化所以性能优化要靠开发者自己控制这一点容易被忽略。最后分享一个习惯我写 action 时会在关键的参数校验失败或请求失败时在代码里直接抛异常或console.warn而不是让每个组件都静默失败。这样一来问题迟早会在开发期暴露出来而不是等到线上才由用户发现。这个小习惯帮我们团队减少了非常多定位问题的时间。Pinia 这个库本身不复杂复杂的是怎么用好它。希望这篇能帮你少走一些弯路。