为什么你应该转向 Pinia

作为一名活跃在 Vue 生态中的开发者，我见证了状态管理解决方案的演变。从最早的简单对象，到 Vuex 各个版本的迭代，再到如今的 Pinia。在过去两年的项目开发中，我完全放弃了 Vuex，转而使用 Pinia，这个决定节省了我大量的开发时间，也让代码变得更加清晰。

Pinia 现在已经成为 Vue 官方推荐的状态管理方案，它具有以下几个显著优势：

更简洁的 API：告别繁琐的 mutations 和 types 常量
完美的 TypeScript 支持：自动类型推导，无需额外类型定义
模块化设计：天生支持多 store 模式，无需 modules 嵌套
更好的开发体验：热模块替换(HMR)支持，开发效率大幅提升
与 Vue 3 的 Composition API 完美结合

下面，我将结合实际项目经验，为你详细解析 Pinia 的使用方法和最佳实践。

快速上手：基础用法

安装与配置

首先，在你的 Vue 项目中安装 Pinia：

npm install pinia
# 或使用yarn
yarn add pinia

然后在应用入口配置 Pinia：

// main.js
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");

创建第一个 Store

使用 Pinia，我们通过defineStore函数来创建 store。与 Vuex 不同，Pinia 鼓励创建多个小型 store，而不是一个庞大的根 store：

// stores/counter.js
import { defineStore } from "pinia";

// defineStore的第一个参数是store的唯一ID
export const useCounterStore = defineStore("counter", {
  // state类似于组件的data
  state: () => ({
    count: 0,
    name: "Counter",
  }),

  // getters类似于组件的computed
  getters: {
    doubleCount: (state) => state.count * 2,
    // 使用this访问其他getters
    doubleCountPlusOne() {
      return this.doubleCount + 1;
    },
  },

  // actions类似于组件的methods
  actions: {
    increment() {
      this.count++;
    },
    async fetchAndAdd(amount) {
      const response = await fetch("/api/value");
      const data = await response.json();
      this.count += data.value + amount;
    },
  },
});

注意命名规范：store 函数通常使用useXxx形式，这与 Vue 3 的组合式函数(Composables)命名风格保持一致。

在组件中使用 Store

现在，让我们在组件中使用刚创建的 store：

<template>
  <div>
    <p>Count: {{ counter.count }}</p>
    <p>Double Count: {{ counter.doubleCount }}</p>
    <button @click="counter.increment()">+1</button>
    <button @click="addRandomValue">Add Random</button>
  </div>
</template>

<script setup>
import { useCounterStore } from "@/stores/counter";

// 获取store实例
const counter = useCounterStore();

// 在组件方法中使用store
const addRandomValue = () => {
  const amount = Math.floor(Math.random() * 10);
  counter.fetchAndAdd(amount);
};
</script>

注意，与 Vuex 不同，使用 Pinia 不需要使用this.$store.state.xxx或mapState这样的语法，直接调用 store 函数获取实例即可，这种 API 设计更加直观和简洁。

深入理解 Pinia 的核心概念

State

Pinia 的 state 是响应式的，可以直接修改，不需要通过 mutations：

const counter = useCounterStore();

// 直接修改state
counter.count++;

// 批量更新state
counter.$patch({
  count: counter.count + 1,
  name: "New Name",
});

// 或者使用函数形式进行更复杂的更新
counter.$patch((state) => {
  state.count += 2;
  state.name = `Modified on ${new Date().toLocaleString()}`;
});

// 完全替换state
counter.$reset(); // 重置为初始状态

在实际项目中，我更推荐使用 actions 来封装状态修改逻辑，而不是在组件中直接修改 state。这样可以保持状态变更的集中管理，便于调试和维护。

Getters

Pinia 的 getters 和 Vuex 类似，但使用更为简单：

defineStore("counter", {
  state: () => ({
    items: [1, 2, 3, 4, 5],
  }),
  getters: {
    // 基本getter
    itemCount: (state) => state.items.length,

    // 接收参数的getter（必须返回一个函数）
    getItemById: (state) => (id) => {
      return state.items.find((item) => item.id === id);
    },

    // 使用其他store的getter
    otherStoreValue(state) {
      // 调用其他store
      const otherStore = useOtherStore();
      return this.itemCount + otherStore.count;
    },
  },
});

在实际项目中，我常用 getters 来处理以下场景：

数据过滤和排序
数据格式转换
数据计算和统计
跨 store 的数据聚合

Actions

Actions 是 Pinia 中处理逻辑和异步操作的地方，相当于 Vuex 中的 actions 和 mutations 的结合：

defineStore("user", {
  state: () => ({
    user: null,
    loading: false,
    error: null,
  }),
  actions: {
    async login(username, password) {
      this.loading = true;
      this.error = null;

      try {
        const user = await api.login(username, password);
        this.user = user;
        return user;
      } catch (err) {
        this.error = err.message;
        throw err;
      } finally {
        this.loading = false;
      }
    },

    logout() {
      this.user = null;
      // 调用其他store的action
      const cartStore = useCartStore();
      cartStore.clearCart();
    },
  },
});

在我的项目实践中，我遵循以下原则组织 actions：

单一职责：每个 action 只做一件事
结果返回：异步 actions 应该返回结果或错误，便于调用方处理
状态跟踪：使用 loading 和 error 等状态记录操作过程
事务完整：如果一个操作涉及多个更改，应封装在一个 action 中

实战应用：构建实用 Store

下面，我会展示一些真实项目中常用的 store 模式，这些模式在我的开发实践中反复验证是有效的。

用户认证 Store

// stores/auth.js
import { defineStore } from "pinia";
import { api } from "@/api";

export const useAuthStore = defineStore("auth", {
  state: () => ({
    user: null,
    token: localStorage.getItem("token") || null,
    loading: false,
    error: null,
  }),

  getters: {
    isAuthenticated: (state) => !!state.token && !!state.user,
    isAdmin: (state) => state.user?.role === "admin",
    userPermissions: (state) => state.user?.permissions || [],
  },

  actions: {
    async login(credentials) {
      this.loading = true;
      this.error = null;

      try {
        const { user, token } = await api.auth.login(credentials);
        this.user = user;
        this.token = token;

        // 持久化token
        localStorage.setItem("token", token);
        return user;
      } catch (error) {
        this.error = error.message;
        throw error;
      } finally {
        this.loading = false;
      }
    },

    async logout() {
      try {
        // 调用登出API（可选）
        if (this.token) {
          await api.auth.logout();
        }
      } catch (error) {
        console.error("Logout API error:", error);
      } finally {
        // 清除状态
        this.user = null;
        this.token = null;
        localStorage.removeItem("token");

        // 重置其他相关store
        const cartStore = useCartStore();
        cartStore.$reset();
      }
    },

    async fetchUserProfile() {
      if (!this.token) return null;

      this.loading = true;
      try {
        const user = await api.auth.getProfile();
        this.user = user;
        return user;
      } catch (error) {
        this.error = error.message;
        // 如果是401错误，说明token已失效
        if (error.status === 401) {
          this.logout();
        }
        throw error;
      } finally {
        this.loading = false;
      }
    },

    // 初始化认证状态，通常在应用启动时调用
    async initialize() {
      if (this.token && !this.user) {
        await this.fetchUserProfile();
      }
    },
  },
});

在应用入口处初始化认证状态：

// App.vue
import { useAuthStore } from "@/stores/auth";

const authStore = useAuthStore();

// 组件挂载时初始化认证状态
onMounted(async () => {
  await authStore.initialize();
});

应用配置 Store

// stores/settings.js
import { defineStore } from "pinia";

export const useSettingsStore = defineStore("settings", {
  state: () => ({
    theme: localStorage.getItem("theme") || "light",
    language:
      localStorage.getItem("language") ||
      navigator.language.split("-")[0] ||
      "en",
    fontSize: parseInt(localStorage.getItem("fontSize")) || 16,
    notifications: JSON.parse(localStorage.getItem("notifications") || "true"),
  }),

  actions: {
    setTheme(theme) {
      this.theme = theme;
      localStorage.setItem("theme", theme);
      // 应用主题
      document.documentElement.setAttribute("data-theme", theme);
    },

    setLanguage(lang) {
      this.language = lang;
      localStorage.setItem("language", lang);
    },

    setFontSize(size) {
      this.fontSize = size;
      localStorage.setItem("fontSize", size.toString());
      // 应用字体大小
      document.documentElement.style.fontSize = `${size}px`;
    },

    toggleNotifications() {
      this.notifications = !this.notifications;
      localStorage.setItem("notifications", JSON.stringify(this.notifications));
    },

    // 初始化应用设置
    initialize() {
      // 应用当前保存的设置
      document.documentElement.setAttribute("data-theme", this.theme);
      document.documentElement.style.fontSize = `${this.fontSize}px`;
      // 可以在这里添加其他初始化逻辑
    },
  },
});

数据列表 Store

// stores/products.js
import { defineStore } from "pinia";
import { api } from "@/api";

export const useProductsStore = defineStore("products", {
  state: () => ({
    items: [],
    total: 0,
    loading: false,
    error: null,
    filters: {
      category: null,
      minPrice: null,
      maxPrice: null,
      search: "",
      sort: "default",
    },
    pagination: {
      page: 1,
      perPage: 20,
      totalPages: 0,
    },
  }),

  getters: {
    filteredItems: (state) => {
      let result = [...state.items];

      // 应用过滤
      if (state.filters.category) {
        result = result.filter(
          (item) => item.category === state.filters.category
        );
      }

      if (state.filters.minPrice !== null) {
        result = result.filter((item) => item.price >= state.filters.minPrice);
      }

      if (state.filters.maxPrice !== null) {
        result = result.filter((item) => item.price <= state.filters.maxPrice);
      }

      if (state.filters.search) {
        const searchLower = state.filters.search.toLowerCase();
        result = result.filter(
          (item) =>
            item.name.toLowerCase().includes(searchLower) ||
            item.description.toLowerCase().includes(searchLower)
        );
      }

      // 应用排序
      switch (state.filters.sort) {
        case "price-asc":
          result.sort((a, b) => a.price - b.price);
          break;
        case "price-desc":
          result.sort((a, b) => b.price - a.price);
          break;
        case "name-asc":
          result.sort((a, b) => a.name.localeCompare(b.name));
          break;
        case "date-desc":
          result.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
          break;
      }

      return result;
    },

    paginatedItems: (state) => {
      const start = (state.pagination.page - 1) * state.pagination.perPage;
      const end = start + state.pagination.perPage;
      return state.filteredItems.slice(start, end);
    },

    getProductById: (state) => (id) => {
      return state.items.find((item) => item.id === id);
    },
  },

  actions: {
    async fetchProducts(options = {}) {
      this.loading = true;
      this.error = null;

      try {
        // 合并筛选和分页参数
        const params = {
          ...this.filters,
          ...this.pagination,
          ...options,
        };

        // 更新当前store的过滤和分页状态
        if (options.category !== undefined)
          this.filters.category = options.category;
        if (options.search !== undefined) this.filters.search = options.search;
        if (options.sort !== undefined) this.filters.sort = options.sort;
        if (options.page !== undefined) this.pagination.page = options.page;

        const { data, total, totalPages } = await api.products.getList(params);

        this.items = data;
        this.total = total;
        this.pagination.totalPages = totalPages;

        return data;
      } catch (error) {
        this.error = error.message;
        throw error;
      } finally {
        this.loading = false;
      }
    },

    async fetchProductDetails(id) {
      // 检查是否已经有完整数据
      const existing = this.items.find((p) => p.id === id && p.isFullData);
      if (existing) return existing;

      this.loading = true;
      try {
        const product = await api.products.getById(id);

        // 标记为完整数据
        product.isFullData = true;

        // 更新或添加到列表
        const index = this.items.findIndex((p) => p.id === id);
        if (index >= 0) {
          this.items[index] = product;
        } else {
          this.items.push(product);
        }

        return product;
      } catch (error) {
        this.error = error.message;
        throw error;
      } finally {
        this.loading = false;
      }
    },

    setFilter(filter, value) {
      this.filters[filter] = value;
      // 重置到第一页
      this.pagination.page = 1;
    },

    clearFilters() {
      this.filters = {
        category: null,
        minPrice: null,
        maxPrice: null,
        search: "",
        sort: "default",
      };
      this.pagination.page = 1;
    },
  },
});

高级技巧：优化和最佳实践

在深入使用 Pinia 的过程中，我总结了一些能够让代码更简洁、性能更好的技巧。

1. 使用组合式 Store

Pinia 支持使用组合式 API 来定义 store，对于复杂 store，这种方式组织代码更加灵活：

// stores/cart.js
import { defineStore } from "pinia";
import { ref, computed } from "vue";
import { api } from "@/api";

export const useCartStore = defineStore("cart", () => {
  // 状态
  const items = ref([]);
  const loading = ref(false);
  const error = ref(null);

  // getters
  const totalItems = computed(() =>
    items.value.reduce((sum, item) => sum + item.quantity, 0)
  );

  const totalPrice = computed(() => {
    return items.value.reduce(
      (sum, item) => sum + item.price * item.quantity,
      0
    );
  });

  const isEmpty = computed(() => items.value.length === 0);

  // actions
  function addItem(product, quantity = 1) {
    const existingItem = items.value.find((item) => item.id === product.id);

    if (existingItem) {
      existingItem.quantity += quantity;
    } else {
      items.value.push({
        id: product.id,
        name: product.name,
        price: product.price,
        image: product.image,
        quantity,
      });
    }
  }

  function removeItem(productId) {
    const index = items.value.findIndex((item) => item.id === productId);
    if (index > -1) {
      items.value.splice(index, 1);
    }
  }

  function updateQuantity(productId, quantity) {
    const item = items.value.find((item) => item.id === productId);
    if (item) {
      item.quantity = Math.max(1, quantity);
    }
  }

  function clearCart() {
    items.value = [];
  }

  async function checkout() {
    if (isEmpty.value) return;

    loading.value = true;
    error.value = null;

    try {
      const order = await api.orders.create({
        items: items.value,
        total: totalPrice.value,
      });

      clearCart();
      return order;
    } catch (err) {
      error.value = err.message;
      throw err;
    } finally {
      loading.value = false;
    }
  }

  return {
    // 暴露状态
    items,
    loading,
    error,

    // 暴露getters
    totalItems,
    totalPrice,
    isEmpty,

    // 暴露actions
    addItem,
    removeItem,
    updateQuantity,
    clearCart,
    checkout,
  };
});

这种写法的好处是：

可以灵活地使用 Vue 的 Composition API 函数
更好的类型推导体验（特别是在 TypeScript 中）
更自然的代码组织方式

2. Store 之间的交互

在大型应用中，各个 Store 之间往往需要相互调用。以下是我在实际项目中使用的最佳实践：

// stores/order.js
import { defineStore } from "pinia";
import { useCartStore } from "./cart";
import { useAuthStore } from "./auth";
import { useNotificationStore } from "./notification";

export const useOrderStore = defineStore("order", {
  // ...state, getters

  actions: {
    async placeOrder() {
      const cartStore = useCartStore();
      const authStore = useAuthStore();
      const notificationStore = useNotificationStore();

      if (!authStore.isAuthenticated) {
        notificationStore.show({
          type: "error",
          message: "请先登录再下单",
        });
        return;
      }

      if (cartStore.isEmpty) {
        notificationStore.show({
          type: "warning",
          message: "购物车为空",
        });
        return;
      }

      this.loading = true;

      try {
        // 创建订单
        const order = await cartStore.checkout();

        // 存储订单信息
        this.orders.push(order);

        // 显示成功消息
        notificationStore.show({
          type: "success",
          message: `订单 #${order.id} 创建成功！`,
        });

        return order;
      } catch (error) {
        notificationStore.show({
          type: "error",
          message: `创建订单失败: ${error.message}`,
        });
        throw error;
      } finally {
        this.loading = false;
      }
    },
  },
});

3. 持久化 Store 状态

在实际应用中，我们常常需要将某些 Store 状态持久化到 localStorage：

// plugins/persistedState.js
import { watch } from "vue";

export function createPersistedState({
  key = "pinia",
  paths = [],
  storage = localStorage,
} = {}) {
  return function ({ store }) {
    // 从storage恢复状态
    const fromStorage = storage.getItem(key);

    if (fromStorage) {
      try {
        store.$patch(JSON.parse(fromStorage));
      } catch (error) {
        console.error("Failed to parse stored state:", error);
      }
    }

    // 监听状态变化并保存
    watch(
      () =>
        paths.length > 0
          ? paths.reduce((partial, path) => {
              partial[path] = store.$state[path];
              return partial;
            }, {})
          : store.$state,
      (state) => {
        storage.setItem(key, JSON.stringify(state));
      },
      { deep: true }
    );
  };
}

使用这个插件：

// stores/cart.js
import { defineStore } from "pinia";
import { createPersistedState } from "@/plugins/persistedState";

export const useCartStore = defineStore("cart", {
  state: () => ({
    items: [],
    recentlyViewed: [],
  }),
  // ...getters, actions
});

// 应用插件
useCartStore().$use(
  createPersistedState({
    key: "cart",
    paths: ["items", "recentlyViewed"],
  })
);

更好的方法是使用现成的库，比如 pinia-plugin-persistedstate：

// main.js
import { createPinia } from "pinia";
import piniaPluginPersistedstate from "pinia-plugin-persistedstate";

const pinia = createPinia();
pinia.use(piniaPluginPersistedstate);

// stores/cart.js
export const useCartStore = defineStore("cart", {
  state: () => ({
    /* ... */
  }),
  // 配置持久化
  persist: {
    key: "cart",
    storage: localStorage,
    paths: ["items", "recentlyViewed"],
  },
});

4. 重置和热更新状态

Pinia 提供了一些实用方法来管理 store 状态：

const store = useCounterStore();

// 重置为初始状态
store.$reset();

// 替换整个state
store.$state = { count: 100, name: "New state" };

// 在开发环境中，热更新store定义
if (import.meta.hot) {
  import.meta.hot.accept(acceptHMRUpdate(useCounterStore, import.meta.hot));
}

结语

从我作为前端开发者的角度来看，Pinia 代表了 Vue 状态管理的未来。它简化了复杂应用的状态管理，同时保持了良好的开发体验和性能。

在我的实际项目中，Pinia 已经完全取代了 Vuex，并且我没有理由再回到 Vuex。特别是当搭配 TypeScript 使用时，Pinia 的类型推导体验远胜 Vuex。

最后，分享一条经验：状态管理工具只是工具，合理的数据流设计和状态划分才是核心。不要为了使用 Pinia 而使用 Pinia，始终考虑你的应用是否需要集中式状态管理，哪些状态应该集中管理，哪些应该保留在组件中。

希望这篇文章能帮助你更好地理解和使用 Pinia！