---

告别 Vuex？认识 Vue 3 官方推荐的状态管理库 Pinia

在 Vue.js 生态中，状态管理一直是大型应用不可或缺的一环。随着应用的复杂度不断提升，如何高效、清晰地管理共享状态成为了开发者必须面对的挑战。曾几何时，Vuex 是这个领域的绝对王者，为无数 Vue 项目提供了强大的状态管理能力。然而，随着 Vue 3 的发布，Composition API 的引入，以及前端技术栈的不断演进，官方对状态管理的推荐也悄然发生了变化。

Pinia，这个名字在 Vue 3 社区中越来越频繁地被提及，并最终被确立为 Vue 3 的官方推荐状态管理库。那么，这是否意味着我们要“告别”陪伴我们多年的 Vuex 了呢？Pinia 究竟有何魅力，能够取代 Vuex 的地位？本文将深入探讨 Pinia 的方方面面，剖析它与 Vuex 的异同，帮助你全面认识这个 Vue 3 时代的“新”状态管理标准。

1. Vuex 的时代贡献与“痛点”

在我们深入了解 Pinia 之前，有必要回顾一下 Vuex 的辉煌历史以及它在实践中暴露的一些“痛点”。

Vuex 诞生于 Vue 2 时代，它借鉴了 Flux 和 Redux 的思想，并将其与 Vue 的响应式系统深度结合，提供了一套集中式状态管理方案。它的核心概念——State、Getters、Mutations、Actions 和 Modules——构建了一个清晰的数据流和状态变更逻辑，有效地解决了组件之间跨层级、跨组件的状态共享和通信问题。对于许多中大型 Vue 2 项目而言，Vuex 是一个稳定、可靠的选择，帮助开发者构建了结构化、可维护的应用。

然而，随着时间的推移，尤其是在 Vue 3 和 TypeScript 逐渐成为主流后，Vuex 的一些设计开始显得有些繁琐和不够现代化：

1. Mutations 的强制性： Vuex 强制要求通过 Mutation 来修改 State。这固然有助于追踪状态变化，但在实际开发中，尤其是一些简单的状态修改，需要定义 Mutation 并通过 commit 调用，增加了不少 boilerplate 代码。
2. Actions 和 Mutations 的区分： 区分 Actions（用于异步操作，通过 dispatch 触发）和 Mutations（用于同步操作，通过 commit 触发）增加了理解成本和代码量。一个简单的同步逻辑有时也需要经过 Action -> Mutation 的流程。
3. TypeScript 支持不够友好： 在 Vue 2 时代的 Vuex 中使用 TypeScript 需要借助一些辅助库或进行额外的类型声明，类型推断不够完善，给开发者带来了不少困扰。虽然 Vuex 4（Vue 3 兼容版本）有所改进，但与原生支持相比仍有差距。
4. Namespacing 的繁琐： 在使用 Modules 进行模块化时，开启 Namespacing 需要手动配置，并在组件中访问时使用字符串路径（如 'moduleA/someAction'），这不仅容易出错，也不利于重构和类型检查。
5. Getters 的类型问题： 在 TypeScript 中，Getters 的返回值类型有时需要手动声明，不如计算属性那样自然。
6. 小型应用的“杀鸡用牛刀”感： 对于一些状态不复杂的小型应用，引入 Vuex 的全套概念和结构会显得过于庞大和笨重。

这些“痛点”并不是否定 Vuex 的价值，而是在技术演进过程中，开发者对状态管理库提出了更高的要求：更简单、更直观、更好的 TypeScript 支持、更灵活的模块化。正是在这样的背景下，Pinia 应运而生。

2. Pinia 的崛起：为什么是它？

Pinia 最初由 Vue 核心团队成员 Egor Borisov 开发，其设计灵感很大程度上来源于 Vuex 5 的早期设计提案。由于 Pinia 在简化 API、增强 TypeScript 支持和模块化方面表现出色，并且与 Vue 3 的 Composition API 天然契合，它很快在社区中流行起来，并最终被 Vue 官方采纳并推荐为 Vue 3 的标准状态管理库。

那么，Pinia 是如何解决 Vuex 的痛点，并带来哪些新优势的呢？

• 极简的 API 设计： 这是 Pinia 最引人注目的特性之一。它取消了 Mutations 的概念，所有同步和异步的状态修改都放在 Actions 中处理。这意味着你可以在 Actions 中直接修改 State，极大地简化了状态变更的流程。核心概念只剩下 State、Getters 和 Actions，大大降低了学习和使用门槛。
• 原生支持 TypeScript： Pinia 被设计时就充分考虑了 TypeScript。它提供了出色的类型推断能力，无论是 State 的属性、Getters 的返回值还是 Actions 的参数和返回值，都能得到很好的类型支持。这为使用 TypeScript 的开发者带来了前所未有的顺畅体验，减少了大量的类型声明工作和潜在的类型错误。
• 真正的模块化和自动命名空间： Pinia 的每一个 Store 都是一个独立的模块，并通过一个唯一的 ID 来定义。这个 ID 自动作为该 Store 的命名空间。在组件中引入和使用 Store 时，无需手动开启 Namespacing，也不用担心命名冲突。这种设计使得 Store 更容易组织、维护和重用。
• 与 Composition API 完美契合： Pinia 设计时就充分利用了 Vue 3 的 Composition API。通过 defineStore 定义 Store，通过 useStore 在组件中引入，这种基于 Hook 的使用方式与 Composition API 的风格高度一致，让开发者能够更自然地组织代码。
• Devtools 支持： Pinia 提供了强大的 Vue Devtools 集成，可以方便地查看 Store 的状态、追踪状态变化（通过 Actions 触发）、甚至进行时间旅行调试。
• 更小的体积： Pinia 的核心代码库比 Vuex 更小，对于追求应用体积优化的项目来说是一个优势。
• 插件系统： Pinia 提供了强大的插件系统，可以轻松扩展 Store 的功能，例如实现持久化存储、添加日志记录等。
• 兼容 Vue 2 和 Vue 3： 虽然 Pinia 是为 Vue 3 设计并推荐的，但它也提供了对 Vue 2 的兼容支持，这为从 Vue 2 迁移到 Vue 3 的项目提供了便利。

总而言之，Pinia 在保持了集中式状态管理核心优势的同时，通过精简 API、拥抱 TypeScript、强化模块化等方式，提供了一个更现代、更简洁、更易用的状态管理解决方案，完美契合了 Vue 3 的技术栈和开发范式。

3. Pinia 的核心概念与使用

理解 Pinia 的核心在于理解如何定义和使用一个 Store。

3.1 定义一个 Store

在 Pinia 中，我们使用 defineStore 函数来定义一个 Store。这是创建 Pinia Store 的入口。

defineStore 接收两个参数：
1. 一个唯一的 ID (字符串)： 这是 Store 的唯一标识符，Pinia 会用它来连接你的 Store 和 Devtools，并作为 Store 的命名空间。
2. 一个选项对象： 这个对象包含了 Store 的实际逻辑，包括 state、getters 和 actions。

“`javascript
// stores/counter.js
import { defineStore } from ‘pinia’;

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

// Getters：定义计算属性，从 state 派生一些状态
// 在 Options API 中，它们接收 state 作为第一个参数
getters: {
doubleCount: (state) => state.count * 2,
// 可以访问其他 getter
doubleCountPlusOne(): number { // 使用 this 访问其他 getters
return this.doubleCount + 1;
},
// 可以返回一个函数，接收参数
getUserById: (state) => (userId) => {
// 假设 state 中有一个 users 数组
// return state.users.find(user => user.id === userId);
return { id: userId, name: User-${userId} }; // 示例
}
},

// Actions：定义方法，用于修改 state 或执行异步操作
// 在 Options API 中，它们可以通过 this 访问 state、getters 和其他 actions
actions: {
increment() {
this.count++; // 直接修改 state
},
decrement() {
this.count–; // 直接修改 state
},
incrementBy(value) {
this.count += value; // 接收参数
},
async fetchSomething() {
// 模拟异步操作
await new Promise(resolve => setTimeout(resolve, 1000));
this.count += 10; // 异步操作完成后修改 state
}
}
});
“`

可以看到，defineStore 返回的是一个 函数 (useCounterStore)。这个函数就是我们在组件中用来获取 Store 实例的 Composition API Hook。

3.2 在组件中使用 Store

在组件中使用 Pinia Store 非常简单，只需调用之前定义好的 useStore Hook 函数即可获取 Store 实例。

“`vue

“`

关于 storeToRefs 的重要说明：

由于 Pinia Store 的 State 和 Getters 是响应式的，当你在组件的 <script setup> 中直接对 Store 实例进行解构时，例如 const { count, doubleCount } = counterStore;，解构出来的 count 和 doubleCount 将会变成普通的值，失去响应性。当 Store 中的 count 变化时，组件中解构出的 count 不会更新，导致视图不会重新渲染。

storeToRefs 是 Pinia 提供的一个辅助函数，它的作用是将 Store 中的 State 属性和 Getters 转换为 Ref 对象。这样，当你使用 storeToRefs 进行解构时，解构出来的仍然是响应式的 Ref，你可以在模板中或进一步在 script setup 中使用它们，而不会丢失响应性。Actions 是函数，调用它们本身不需要响应性，所以可以直接从 Store 实例中解构。

在 Options API 中，可以使用 Pinia 提供的 mapState、mapGetters (注意 Pinia 将 State 和 Getters 统一到了 mapState 中使用)、mapActions 或 mapStores 辅助函数来将 Store 的内容映射到组件的计算属性或方法中，这些辅助函数会自动处理响应性。但 Pinia 更推荐在 Vue 3 中使用 Composition API 结合 storeToRefs 的方式。

3.3 安装与集成

在 Vue 3 项目中使用 Pinia，首先需要安装它：

“`bash
npm install pinia

或者

yarn add pinia

或者

pnpm add pinia
“`

然后，在你的 Vue 应用的入口文件（通常是 main.js 或 main.ts）中创建 Pinia 实例并将其挂载到 Vue 应用上：

“`javascript
// 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’);
“`

这样，Pinia 就已经在你的 Vue 应用中准备就绪了，你可以在任何组件中使用 useStore Hook 来访问和操作 Store。

4. Pinia 与 Vuex 的详细对比

为了更直观地理解 Pinia 的优势，我们来对 Pinia 和 Vuex 的关键特性进行详细对比。

特性/概念	Vuex (Vue 3 Compatible – v4)	Pinia	对比分析
核心概念	State, Getters, Mutations, Actions, Modules	State, Getters, Actions, Stores (隐式模块)	Pinia 移除了 Mutations，精简了概念，降低了学习成本。
状态修改方式	必须通过 commit 触发 Mutations 来同步修改 State。	在 Actions 中直接通过 this 访问 State 并修改。取消了 Mutation。	Pinia 更直接，减少了 boilerplate。Vuex 的 Mutations 强制性提高了状态追踪的可维护性，但增加了代码量。
异步操作	在 Actions 中通过 dispatch 触发，Actions 可以包含异步逻辑，但不能直接修改 State，最终需通过 Mutations 修改。	在 Actions 中直接执行异步逻辑，并在完成后直接修改 State。	Pinia 更简洁，Actions 集成了异步和同步状态修改的能力。
模块化	通过 modules 选项定义模块，需要手动配置 namespaced 选项。	每个 defineStore 创建的都是一个独立的 Store，天然就是模块化的，ID 即命名空间。	Pinia 的模块化更原生、更自动化，避免了 Namespacing 的配置和访问繁琐。
命名空间访问	在组件中访问模块内容需要使用字符串路径（如 moduleA/someAction）。	在组件中通过 useStore 获取 Store 实例，直接访问其属性和方法即可。	Pinia 访问更直观，无需字符串路径，重构友好。
TypeScript 支持	需要额外的类型声明和辅助函数，类型推断相对有限。Vuex 4 有所改进，但仍不如 Pinia 原生。	原生支持 TypeScript，提供优秀的类型推断能力，几乎无需手动声明。	Pinia 在 TS 环境下的开发体验远超 Vuex，是 TS 项目的首选。
组件访问辅助函数	mapState, mapGetters, mapActions, mapMutations, createNamespacedHelpers	mapState, mapActions, mapStores, storeToRefs	Pinia 也提供了 map 辅助函数用于 Options API，但在 Composition API 中更推荐 useStore 结合 storeToRefs。
Hooks 支持 (Composition API)	勉强兼容，但不如 Pinia 原生。	原生基于 Hook 设计 (useStore)，与 Composition API 完美契合。	Pinia 更符合 Vue 3 的开发风格。
Devtools	支持。	支持，提供更友好的体验，Actions 列表直接展示状态变更。	Pinia 的 Devtools 集成更深入、更直观。
代码量 (Boilerplate)	相对较多，尤其是有 Mutation 层。	相对较少，取消 Mutation，简化 Actions。	Pinia 更轻量级，定义和使用 Store 的代码更少。
体积	稍大。	更小。	Pinia 更轻量。
插件系统	支持。	支持，设计更灵活。	Pinia 插件系统易于扩展。
Vue 版本兼容	Vue 2 (v3), Vue 3 (v4)	Vue 2 (with bridge), Vue 3 (原生支持)	Pinia 主要为 Vue 3 设计，但提供了 Vue 2 兼容层。

通过对比可以清楚地看到，Pinia 在简化 API、提升开发者体验（尤其是 TypeScript 和 Composition API 用户）、优化模块化等方面相对于 Vuex 有着显著的进步。它保留了状态管理的核心功能，同时剔除了 Vuex 中一些被认为繁琐或不够现代的设计。

5. “告别 Vuex” 意味着什么？

将 Pinia 称为 Vue 3 的“官方推荐”状态管理库，并不是说 Vuex 不再可用或不再维护。Vuex 4 是为 Vue 3 发布的兼容版本，它仍然可以使用在 Vue 3 项目中，特别是对于从 Vue 2 迁移过来的大型项目，可能选择逐步迁移而非一次性替换 Vuex。

“告别 Vuex” 更准确的理解是：

1. 官方未来发展的重心转移： Pinia 代表了 Vue 核心团队对未来状态管理库的设想，后续的新特性、优化和生态建设将主要围绕 Pinia 进行。
2. 新项目的首选： 对于新的 Vue 3 项目，官方明确推荐使用 Pinia，因为它与 Vue 3 的技术栈结合更紧密，开发体验更佳。
3. 知识和社区趋势： 社区的关注点和新的最佳实践将逐渐向 Pinia 倾斜，相关的教程、插件和招聘需求也会越来越多地提及 Pinia。

所以，如果你正在启动一个新的 Vue 3 项目，毫无疑问应该选择 Pinia。如果你有一个现有的 Vuex 项目，可以考虑在新增模块时尝试使用 Pinia，或者制定一个逐步迁移的计划。Pinia 和 Vuex 可以在同一个 Vue 3 应用中同时存在一段时间，这为平滑过渡提供了可能性。

6. Pinia 的进阶使用和特性

除了核心概念，Pinia 还提供了一些高级特性和常用模式：

• Store 之间的交互： 一个 Store 可以通过 useStore Hook 在其 Actions 或 Getters 中访问另一个 Store，实现跨 Store 的状态访问和方法调用。

  “`javascript
  // stores/user.js
  import { defineStore } from ‘pinia’;
  import { useCounterStore } from ‘./counter’; // 引入另一个 store

  export const useUserStore = defineStore(‘user’, {
  state: () => ({
  userInfo: null
  }),
  actions: {
  async login(credentials) {
  // … login logic
  this.userInfo = { name: ‘Admin’, id: 1 };

    // 访问并调用 counterStore 的 action
    const counterStore = useCounterStore();
    counterStore.incrementBy(100);
  }
  

  }
  });
  “`

• 插件系统： Pinia 的插件系统允许你在创建 Pinia 实例时注入自定义逻辑，以扩展所有 Store 的功能。插件可以添加新的状态、方法、选项，或者对现有功能进行拦截。

  “`javascript
  // main.js
  import { createPinia } from ‘pinia’;

  const pinia = createPinia();

  // 定义一个简单的日志插件
  pinia.use(({ store }) => {
  // 在每个 store 的 action 执行前/后执行
  store.$onAction(({
  name, // action 名称
  store, // store 实例
  args, // 参数
  after, // action 成功执行后调用的函数
  onError, // action 执行出错后调用的函数
  }) => {
  const startTime = Date.now();
  console.log(Start "${name}" with params ${JSON.stringify(args)}.);

  after((result) => {
    console.log(`End "${name}" in ${Date.now() - startTime}ms.\nResult: ${JSON.stringify(result)}.`);
  });
  
  onError((error) => {
    console.error(`Failed "${name}" in ${Date.now() - startTime}ms.\nError: ${error}.`);
  });
  

  });
  });

  // … rest of your app setup
  “`

• 状态订阅 ($subscribe)： 你可以订阅 Store 的状态变化，并在变化发生时执行回调函数。这对于将 Store 状态同步到本地存储等场景非常有用。

  “`javascript
  import { watch } from ‘vue’;
  import { useCounterStore } from ‘@/stores/counter’;

  const counterStore = useCounterStore();

  // 订阅整个 state 的变化
  counterStore.$subscribe((mutation, state) => {
  console.log(‘State has changed:’, state);
  // 例如：将 state 同步到 localStorage
  // localStorage.setItem(‘counterState’, JSON.stringify(state));
  });

  // 也可以 watch 某个特定的 getter 或 state 属性 (使用 Vue 的 watch 函数)
  watch(() => counterStore.doubleCount, (newVal, oldVal) => {
  console.log(‘doubleCount changed:’, newVal, oldVal);
  });
  “`

• State Patching ($patch)： Pinia 提供了 $patch 方法来批量更新 State，这对于一次性修改多个 State 属性时性能更优，因为它会将多次修改合并为一次 Devtools 快照。

  “`javascript
  const counterStore = useCounterStore();

  // 使用对象方式 patch
  counterStore.$patch({
  count: counterStore.count + 1,
  name: ‘New Name’
  });

  // 使用函数方式 patch (更灵活，可以基于当前 state 计算新值)
  counterStore.$patch(state => {
  state.count++;
  state.name = ‘Updated ‘ + state.name;
  });
  “`

这些进阶特性使得 Pinia 不仅简单易用，同时也非常强大和灵活，能够满足各种复杂的应用场景需求。

7. 总结：拥抱 Pinia 的未来

Pinia 作为 Vue 3 官方推荐的状态管理库，凭借其简洁的 API、一流的 TypeScript 支持、原生的模块化和与 Composition API 的完美集成，为 Vue 开发者带来了前所未有的开发体验提升。它有效地解决了 Vuex 在 Vue 3 时代的一些“痛点”，让状态管理变得更加直观、高效和愉快。

虽然“告别 Vuex”的说法可能略显绝对，毕竟 Vuex 仍将继续存在和维护一段时间，但毫无疑问，Pinia 代表着 Vue 状态管理的未来方向。对于新的 Vue 3 项目，选择 Pinia 已经成为主流和最佳实践。对于现有项目，即使不立即迁移，了解和学习 Pinia 也是非常有价值的，它将为你提供更现代的状态管理思路和工具。

从 Vuex 到 Pinia，这不是简单的替代，而是生态系统的自然演进和优化。Pinia 汲取了 Vuex 的经验，结合 Vue 3 的新特性，为我们提供了一个更强大、更易用的状态管理解决方案。现在，是时候拥抱 Pinia，享受它带来的开发便利了！

希望本文为你全面认识 Pinia 并理解其在 Vue 3 生态中的地位提供了详细的指导。现在，就开始在你的项目中使用 Pinia 吧！

---