Pinia 状态管理完全指南：Store 设计、持久化、SSR 兼容与生产级实践

// stores/counter.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

// 命名规范：use + Store 名
export const useCounterStore = defineStore('counter', () => {
  // ========== State ==========
  const count = ref(0)
  const items = ref<string[]>([])

  // ========== Getters ==========
  const doubleCount = computed(() => count.value * 2)
  const itemCount = computed(() => items.value.length)

  // ========== Actions ==========
  function increment() {
    count.value++
  }

  function addItem(item: string) {
    items.value.push(item)
  }

  function $reset() {
    count.value = 0
    items.value = []
  }

  return { count, items, doubleCount, itemCount, increment, addItem, $reset }
})

<script setup>
import { useCounterStore } from '@/stores/counter'
import { storeToRefs } from 'pinia'

const store = useCounterStore()

// 解构保持响应性（必须用 storeToRefs）
const { count, doubleCount } = storeToRefs(store)

// 可以直接修改 state（不需要 mutation）
const increase = () => {
  store.increment()
  // 或：store.count++
}

// $reset
const reset = () => store.$reset()
</script>

<template>
  <div>
    <p>Count: {{ count }}</p>
    <p>Double: {{ doubleCount }}</p>
    <button @click="increase">+1</button>
    <button @click="reset">Reset</button>
  </div>
</template>

export const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0, items: [] as string[] }),
  getters: {
    doubleCount: (state) => state.count * 2,
    itemCount: (state) => state.items.length,
  },
  actions: {
    increment() {
      this.count++
    },
    addItem(item: string) {
      this.items.push(item)
    },
  },
})

// stores/cart.ts
import { useAuthStore } from './auth'

export const useCartStore = defineStore('cart', () => {
  const items = ref<CartItem[]>([])

  async function checkout() {
    const auth = useAuthStore()  // 在其他 store 中获取
    if (!auth.isLoggedIn) {
      throw new Error('Please login first')
    }
    await api.checkout({ items: items.value, userId: auth.user?.id })
    items.value = []
  }

  return { items, checkout }
})

// stores/index.ts
export { useAuthStore } from './auth'
export { useUserStore } from './user'
export { useCartStore } from './cart'
export { useUIStore } from './ui'

// plugins/piniaStorage.ts
import { PiniaPluginContext } from 'pinia'

export function piniaStoragePlugin(context: PiniaPluginContext) {
  const { store } = context

  // 从 localStorage 恢复
  const saved = localStorage.getItem(store.$id)
  if (saved) {
    store.$patch(JSON.parse(saved))
  }

  // 订阅变化并保存
  store.$subscribe((mutation, state) => {
    localStorage.setItem(store.$id, JSON.stringify(state))
  })
}

// main.ts
import { createPinia } from 'pinia'
import { piniaStoragePlugin } from './plugins/piniaStorage'

const pinia = createPinia()
pinia.use(piniaStoragePlugin)

npm install pinia-plugin-persistedstate

// main.ts
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'
pinia.use(piniaPluginPersistedstate)

// stores/auth.ts
export const useAuthStore = defineStore('auth', () => {
  // ...
}, {
  persist: {
    storage: localStorage,           // 默认 localStorage
    paths: ['token', 'user'],        // 只持久化这些字段
  },
})

// Nuxt.js / SSR 项目
// 使用 $fetchState 或 ensure data is fetched

export const useProductStore = defineStore('product', () => {
  const products = ref<Product[]>([])
  const loading = ref(false)

  async function fetchProducts() {
    if (products.value.length) return  // SSR 时已获取则跳过
    loading.value = true
    products.value = await $fetch('/api/products')  // Nuxt 的 $fetch
    loading.value = false
  }

  return { products, loading, fetchProducts }
})

// 在页面中
<script setup>
const productStore = useProductStore()
await productStore.fetchProducts()  // await 确保 SSR 完成后再渲染
</script>

export const useStore = defineStore('store', () => {
  const loading = ref(false)

  async function fetchData() {
    loading.value = true
    try {
      const data = await api.fetch()
      return data
    } finally {
      loading.value = false
    }
  }

  return { loading, fetchData }
})

// 使用
const data = await store.fetchData()