---

Pinia 初学者指南：迈出 Vue 状态管理第一步

欢迎来到 Vue.js 的世界！当你开始构建功能越来越复杂的应用程序时，你会发现组件之间共享数据和状态变得越来越具有挑战性。props 逐层传递（prop drilling）可能会变得非常繁琐，而通过事件来回通信则容易变得混乱。这就是 状态管理 派上用场的时候了。

对于 Vue 3，官方推荐的状态管理库是 Pinia。它被认为是 Vuex 5 的实际实现，提供了更简洁、更直观的 API，并且对 TypeScript 提供了出色的支持。如果你是 Vue 的新手，或者正在从 Vue 2/Vuex 迁移到 Vue 3，Pinia 绝对是你应该学习的首选状态管理方案。

本文将作为你的 Pinia 初学者指南，带你了解 Pinia 的核心概念，学习如何在你的 Vue 3 项目中集成和使用它，从而告别组件之间复杂的数据传递。

让我们开始吧！

为什么需要状态管理？

在深入 Pinia 之前，让我们先理解为什么在某些场景下需要状态管理。

想象一下，你正在构建一个电商网站。网站有用户登录状态、购物车信息、商品列表筛选条件等等。这些信息可能需要在应用程序中的许多不同组件中访问和修改。

• 用户登录状态： 导航栏需要知道用户是否登录来显示“登录”或“退出”按钮以及用户信息。个人中心页面需要这些信息。购物车页面可能也需要根据登录状态来决定是否显示某些功能。
• 购物车信息： 商品列表页面的“添加到购物车”按钮需要更新购物车数据。导航栏需要显示购物车中商品的数量。购物车页面则需要展示购物车详情并进行结算。

如果仅依赖组件自身的状态 (data 选项或 ref/reactive) 和父子组件之间的 props/events 通信：

1. 数据传递复杂： 你可能需要将数据从一个遥远的父组件通过多层子组件传递下去（props drilling），反之亦然，通过层层事件向上传递。这使得组件耦合度高，难以维护和理解。
2. 状态同步困难： 当多个组件需要访问和修改同一份数据时，手动同步这些状态会非常容易出错。例如，一个组件更新了购物车，另一个显示购物车总数的组件如何得知并更新？
3. 全局状态缺失： 有些状态是应用程序级别的，不属于任何特定的组件。例如，当前用户的主题设置、国际化语言选择等。

状态管理模式提供了一个解决方案：它将应用程序的全局状态集中存储在一个地方，所有组件都可以直接从这个地方读取状态，并通过定义好的方式（通常是 action 或 mutation）修改状态。这就像建立了一个“中央数据中心”，所有需要数据的组件都来这里获取，需要修改数据时也通过特定的“通道”进行操作。

这样做的好处是：

• 数据集中： 状态统一管理，易于追踪和调试。
• 逻辑清晰： 状态的读取和修改方式标准化，降低了出错的可能性。
• 组件解耦： 组件不再需要关心数据的来源和传递路径，它们只需要知道如何与“中央数据中心”交互。

Pinia 就是 Vue 3 官方推荐的“中央数据中心”构建工具。

为什么选择 Pinia 而不是 Vuex？

Vuex 是 Vue 2 生态系统中非常流行的状态管理库，它也适用于 Vue 3。然而，Pinia 是为 Vue 3 量身定制的，并提供了许多改进：

1. 更简洁的 API： Pinia 大大简化了概念。它移除了 Mutations（状态修改直接在 Actions 中完成），也不再有 Module 嵌套的复杂性（虽然你仍然可以组织多个 Store，但它们是扁平的）。这使得学习和使用 Pinia 更加直观。
2. 出色的 TypeScript 支持： Pinia 从设计之初就考虑了 TypeScript。使用 Pinia，你可以获得更好的类型推断，编写更健壮的代码。
3. 更小的体积： Pinia 的核心代码比 Vuex 更小。
4. Vue Devtools 支持： Pinia 在 Vue Devtools 中提供了非常好的支持，你可以方便地查看状态、跟踪状态变化和时间旅行调试。
5. 模块化设计： Pinia 的 Store 本身就是模块化的，你可以轻松地定义和使用多个 Store，每个 Store 负责应用状态的一部分。

对于新的 Vue 3 项目，强烈建议使用 Pinia。如果你正在维护一个大型的 Vue 2/Vuex 项目，可以考虑逐步迁移，但对于初学者来说，直接学习 Pinia 是最明智的选择。

开始使用 Pinia：安装与集成

首先，你需要有一个 Vue 3 项目。你可以使用 Vue CLI 或 Vite 创建一个。

“`bash

使用 Vue CLI

vue create my-pinia-app

选择 Vue 3

或者使用 Vite

npm create vue@latest

选择 Vue，然后选择 Vanilla JS 或 TypeScript

“`

进入项目目录：

bash
cd my-pinia-app

安装 Pinia：

“`bash
npm install pinia

或者

yarn add pinia

或者

pnpm add pinia
“`

安装完成后，你需要在 Vue 应用程序的入口文件（通常是 src/main.js 或 src/main.ts）中创建 Pinia 实例并将其集成到 Vue 应用中。

“`javascript
// src/main.js
import { createApp } from ‘vue’
import { createPinia } from ‘pinia’ // 导入 createPinia
import App from ‘./App.vue’

const app = createApp(App)
const pinia = createPinia() // 创建 Pinia 实例

app.use(pinia) // 将 Pinia 实例挂载到 Vue 应用上
app.mount(‘#app’)
“`

“`typescript
// src/main.ts (如果使用 TypeScript)
import { createApp } from ‘vue’
import { createPinia } from ‘pinia’ // 导入 createPinia
import App from ‘./App.vue’

const app = createApp(App)
const pinia = createPinia() // 创建 Pinia 实例

app.use(pinia) // 将 Pinia 实例挂载到 Vue 应用上
app.mount(‘#app’)
“`

这样，你的 Vue 3 应用程序就成功集成了 Pinia。接下来，我们将学习 Pinia 的核心概念。

Pinia 的核心概念：Store

在 Pinia 中，Store 是状态管理的中心。你可以将 Store 想象成应用程序中一个特定部分的“大脑”或“数据仓库”。例如，你可以创建一个 userStore 来管理用户相关状态（登录状态、用户信息），一个 cartStore 来管理购物车状态，一个 settingsStore 来管理应用设置等。

每个 Store 都是使用 defineStore 函数定义的。defineStore 接收两个参数：

1. 一个唯一的 ID (字符串)： 这是 Store 的唯一标识符，Pinia 使用它来连接 Devtools 并允许 Pinia 了解不同的 Store。这个 ID 是必需的，并且必须是唯一的。
2. 一个选项对象： 这个对象定义了 Store 的实际内容，包括 state, getters, 和 actions。

“`javascript
// 示例：定义一个简单的计数器 Store
import { defineStore } from ‘pinia’

export const useCounterStore = defineStore(‘counter’, {
// state 是一个函数，返回 Store 的初始状态
state: () => ({
count: 0,
name: ‘Eduardo’,
}),

// getters 是一个对象，定义了基于 state 的派生状态 (类似 computed)
getters: {
doubleCount: (state) => state.count * 2,
// 你也可以在 getter 中访问其他 getter
doubleCountPlusOne(): number { // 使用函数简写和类型标注
return this.doubleCount + 1
},
// Getter 也可以接收参数 (返回一个函数)
getCounterById: (state) => {
return (id: number) => Counter ID: ${id}, Value: ${state.count}
}
},

// actions 是一个对象，定义了修改 state 的方法 (可以是同步或异步)
actions: {
increment() {
this.count++ // 直接修改 state
},
incrementBy(value: number) {
this.count += value
},
async incrementAsync() {
await new Promise(resolve => setTimeout(resolve, 1000))
this.count++
},
// Action 也可以访问其他 action 或 getter
// 例如，一个 action 可以调用另一个 action 或 getter
},
})
“`

让我们逐一详细看看 state, getters, 和 actions。

State：Store 的数据

state 是 Store 的核心，它包含了你想要共享的所有数据。在 Pinia 中，state 被定义为一个返回初始状态对象的函数：

javascript
state: () => ({
count: 0,
user: {
name: '未登录',
isLoggedIn: false
},
items: []
})

为什么是一个函数？ 返回一个函数可以确保每个 Store 实例都有一个独立的 state 对象，这对于在服务器端渲染 (SSR) 中避免状态污染非常重要。即使你不做 SSR，这也是 Pinia 推荐的标准方式。

State 中的数据是响应式的。当 state 中的数据发生变化时，所有使用这些数据的组件都会自动更新。

Getters：派生状态

getters 允许你定义基于 state 的派生状态，就像 Vue 组件中的 computed 属性一样。Getter 的结果会被缓存，只有当其依赖的 state 发生变化时才会重新计算。

getters 是一个对象，每个属性都是一个函数，接收 state 作为第一个参数：

javascript
getters: {
// 接收 state 参数
doubleCount: (state) => state.count * 2,
isLoggedIn: (state) => state.user.isLoggedIn,
totalItems: (state) => state.items.length
}

你也可以使用 this 访问 Store 的其他部分，包括其他 getters。在这种情况下，通常使用标准函数语法（而不是箭头函数），以便 this 指向 Store 实例：

javascript
getters: {
doubleCount: (state) => state.count * 2,
// 使用函数语法访问其他 getter
doubleCountPlusOne(): number {
return this.doubleCount + 1;
}
}

Getters 也可以接受参数，此时它应该返回一个函数：

javascript
getters: {
getItemById: (state) => {
return (itemId: number) => state.items.find(item => item.id === itemId);
}
}

Actions：修改状态与业务逻辑

actions 是执行业务逻辑和修改 state 的地方。Actions 可以是同步的，也可以是异步的。与 Vuex 不同的是，Pinia 没有 mutations 的概念，直接在 Actions 中通过 this 访问和修改 state 是被允许的。

actions 是一个对象，每个属性都是一个方法：

“`javascript
actions: {
// 同步 Action
increment() {
this.count++ // 直接修改 state
},
login(userData) {
this.user.name = userData.name;
this.user.isLoggedIn = true;
},
addItem(item) {
this.items.push(item);
},

// 异步 Action
async fetchItems() {
const response = await fetch(‘/api/items’);
const data = await response.json();
this.items = data; // 在异步操作完成后修改 state
},

// Action 也可以调用其他 Action 或 Getter
async loginAndFetchItems(userData) {
this.login(userData); // 调用另一个 Action
await this.fetchItems(); // 调用一个异步 Action
},

// Action 也可以访问 Getter
logDoubleCount() {
console.log(‘Double Count:’, this.doubleCount); // 访问 Getter
}
}
“`

在 actions 中，你可以通过 this 访问整个 Store 实例，包括 state, getters, 和其他 actions。这是进行复杂业务逻辑处理的理想场所。

在组件中使用 Store

定义好 Store 后，下一步就是在 Vue 组件中使用它。

首先，你需要在组件中导入你的 Store 定义：

javascript
import { useCounterStore } from '../stores/counter' // 假设你的 Store 文件在 src/stores 目录下

然后，在组件的 setup 函数（对于 Composition API）或其他适当的地方（如果你还在用 Options API，虽然 Pinia 更适合 Composition API）调用 Store 的 hook 函数来获取 Store 实例：

“`vue

“`

重点注意 storeToRefs!

这是一个初学者常犯的错误：直接解构从 useStore() 返回的 Store 实例的 state 或 getters。

javascript
const store = useCounterStore()
const { count, doubleCount } = store // ❌ 错误，count 和 doubleCount 现在是普通的数字，不再是响应式的

这样做的问题是，count 和 doubleCount 变量将只获取到 state 当前的值，它们与 Store 中的原始 state 失去了连接。当 Store 中的 count 实际发生变化时，组件中的 count 和 doubleCount 不会自动更新，从而导致视图不会刷新。

为了解决这个问题，Pinia 提供了一个工具函数 storeToRefs。它会为 Store 中的所有响应式属性（state 和 getters）创建 ref，然后你可以安全地解构这些 ref：

“`javascript
import { storeToRefs } from ‘pinia’

const counterStore = useCounterStore()
const { count, doubleCount } = storeToRefs(counterStore) // ✅ 正确，count 和 doubleCount 都是 ref，并且是响应式的
“`

现在，count 和 doubleCount 都是响应式的 ref，当 Store 的 state 改变时，它们也会自动更新，从而触发组件的重新渲染。

Actions 则不同。Actions 是函数，你直接解构它们并调用是完全没问题的，因为你调用的是 Store 实例上的同一个函数引用，函数内部通过 this 访问 Store 的 state 仍然是响应式的。所以 Actions 可以直接解构：

javascript
const { increment, incrementAsync } = counterStore // ✅ Actions 可以直接解构

总结在组件中使用 Store 的步骤：

1. 导入 Store 定义：import { useMyStore } from '...'
2. 在 setup 中调用 Store hook 获取实例：const myStore = useMyStore()
3. 使用 storeToRefs(myStore) 解构响应式的 state 和 getters 属性。
4. 直接从 Store 实例解构 actions 方法。
5. 在模板中像使用普通 ref 或函数一样使用解构出来的变量和方法。

修改 State 的几种方式

虽然我们强调 Actions 是进行复杂状态修改和业务逻辑的地方，但在某些简单场景下，你也可以直接修改 state。Pinia 提供了几种修改 state 的方式：

1. 直接修改： 这是最简单的方式，尤其是在 Actions 中。

   javascript
actions: {
increment() {
this.count++
}
}
// 在组件中调用 store.increment()

   你甚至可以在组件中直接修改 Store 的 state（虽然不推荐用于复杂逻辑）：

   vue
<template>
<button @click="counterStore.count++">直接增加 Count</button>
</template>
<script setup>
import { useCounterStore } from '../stores/counter'
const counterStore = useCounterStore()
</script>
   这种直接修改的方式对于非常简单的场景是可以的，但在 Actions 中进行修改通常是更好的实践，因为它将状态修改的逻辑集中管理。

2. 使用 $patch 方法： 当你需要进行多个 state 属性的修改时，$patch 方法会更高效。它允许你批量地修改 state，从而优化性能。

   $patch 可以接收一个对象，对象的属性对应 state 中要修改的属性：

   javascript
actions: {
changeNameAndIncrement() {
this.$patch({
count: this.count + 1,
name: '新的名字'
})
}
}

   $patch 也可以接收一个函数，函数接收 state 作为参数，你可以在函数中直接修改 state 对象：

   javascript
actions: {
incrementAndChangeName(newName) {
this.$patch((state) => {
state.count++
state.name = newName
})
}
}
   使用 $patch 的函数形式，可以在一次操作中完成多个 state 属性的修改，并且支持更复杂的逻辑。

3. 替换整个 state： 你可以使用 store.$state = { ... } 来完全替换 Store 的 state。但这是一种比较极端的做法，通常不推荐，除非你有非常特殊的理由。

   javascript
actions: {
resetState() {
this.$state = { // 用初始值替换整个 state
count: 0,
name: 'Eduardo',
items: [] // 如果你的 state 中有 items
}
}
}

   你也可以使用 store.$reset() 方法，如果你的 state 是一个返回对象的函数，它会调用这个函数来重置 state 到初始值。

   javascript
actions: {
reset() {
this.$reset(); // 调用 state 函数，重置 state 到初始值
}
}

Pinia 与 Vue Devtools

Pinia 与 Vue Devtools 集成得非常好，这为调试带来了极大的便利。安装 Vue Devtools 浏览器扩展后，你可以在浏览器的开发者工具中找到 Vue 选项卡。

在 Vue 选项卡中，你会看到 Pinia 的面板。在这里，你可以：

• 查看所有的 Store： 列出你的应用程序中定义和使用的所有 Pinia Store。
• 检查 State： 查看每个 Store 的当前状态，包括所有 state 属性的值。
• 追踪 Actions： 查看已经分发的所有 Actions 的历史记录。你可以点击 Actions 查看它们的详细信息，包括它们是在哪个组件中触发的、传递了哪些参数等。
• 时间旅行调试 (Time Travel Debugging)： 在 Action 历史记录中，你可以点击回退按钮，将 Store 的状态回退到某个 Action 发生之前的状态，这对于调试非常有用。
• 手动修改 State： 在 Devtools 中直接修改 Store 的 state（仅用于调试）。

强大的 Devtools 支持使得理解应用程序的状态流转和定位问题变得更加容易。

组织你的 Stores

随着应用程序的增长，你可能会定义多个 Store。为了保持代码的整洁和可维护性，推荐将 Store 文件组织在一个单独的目录下，例如 src/stores。

src/
├── components/
├── stores/
│ ├── counter.js
│ ├── user.js
│ ├── cart.js
│ └── index.js // 可以选择性地创建一个 index 文件统一导出所有 store
├── App.vue
├── main.js
└── ...

在 src/stores/index.js 中，你可以将所有 Store 定义统一导出：

javascript
// src/stores/index.js
export * from './counter'
export * from './user'
export * from './cart'
// ... 导出其他 Store

然后在需要使用 Store 的组件中，可以直接从 src/stores 导入：

javascript
// 在组件中
import { useCounterStore, useUserStore } from '../stores'
// ... 使用 useCounterStore() 和 useUserStore()

这种组织方式使得 Store 的管理更加清晰。

总结与下一步

恭喜你！你已经迈出了学习 Pinia 和 Vue 状态管理的第一步。我们学习了：

• 为什么需要状态管理。
• Pinia 相较于 Vuex 的优势。
• 如何在 Vue 3 项目中安装和集成 Pinia。
• Pinia 的核心概念：Store，以及 Store 的组成部分：State, Getters, Actions。
• 如何使用 defineStore 定义一个 Store。
• 如何在组件中使用 Store，以及如何正确地使用 storeToRefs 来解构 state 和 getters。
• 修改 state 的几种方式：直接修改、$patch 对象/函数、$state 替换和 $reset。
• Pinia 与 Vue Devtools 的集成。
• 组织多个 Store 的建议。

Pinia 提供了一种直观且高效的方式来管理 Vue 应用程序的状态。它的简洁性、强大的 TypeScript 支持以及良好的 Devtools 集成，使其成为 Vue 3 开发者的首选。

这只是 Pinia 的冰山一角。Pinia 还有更多高级特性，例如：

• Plugins： 扩展 Pinia 功能的强大机制，可以用于实现状态持久化 (Persistence)、自定义 Devtools 集成、添加全局属性等。
• Composition API 风格的 Store 定义： 除了我们介绍的 Options API 风格 (state, getters, actions 对象)，defineStore 也可以接收一个 setup 函数，允许你使用 Composition API 的方式定义 Store。

作为初学者，掌握 State, Getters, Actions 以及如何在组件中正确使用 storeToRefs 已经足够你处理大多数常见的状态管理场景了。

接下来，建议你：

1. 动手实践： 尝试在一个小型 Vue 3 项目中实现一个简单的计数器或待办事项列表应用，使用 Pinia 来管理状态。
2. 查阅官方文档： Pinia 的官方文档 (https://pinia.vuejs.org/) 非常详细和易于理解，是学习高级特性和深入了解 Pinia 的最佳资源。
3. 探索 Plugins： 了解如何使用社区提供的 Pinia Plugins（例如 pinia-plugin-persistedstate 用于状态持久化）来扩展 Pinia 的能力。

状态管理是构建大型单页应用（SPA）不可或缺的一部分。掌握 Pinia 将极大地提升你开发 Vue 应用程序的效率和代码质量。

祝你在 Pinia 的学习旅程中一切顺利！

---