Pinia 从 v1 迁移到 v2 完全指南

前言

Pinia 作为 Vue 官方推荐的状态管理库，在 2.0 版本中实现了对 Vue 2 和 Vue 3 的双重支持。本文将为正在使用 Pinia v1 的用户提供详尽的迁移指南，帮助您平滑过渡到 v2 版本。

迁移准备

检查当前版本

在开始迁移前，请确保您已安装最新版的 Pinia v1：

npm install 'pinia@^0.x.x'
# 或使用 yarn
yarn add 'pinia@^0.x.x'

使用 ESLint 检测废弃 API

推荐使用 ESLint 的 deprecation 插件来识别代码中所有已废弃的 API 用法。这些 API 在 v2 中已被移除：

• createStore() → 改为 defineStore()
• 订阅中的 storeName → 改为 storeId
• PiniaPlugin → 重命名为 PiniaVuePlugin（Vue 2 专用）
• $subscribe() 不再接受布尔值作为第二参数，需改为对象形式 { detached: true }
• Pinia 插件不再直接接收 store 的 id，改用 store.$id

主要变更点

类型系统更新

1. 通用 Store 类型变更：
   • GenericStore 类型 → 改为 StoreGeneric
   • 无泛型的 Store 类型现在表示空 store 类型，应改用 StoreGeneric

// 旧写法
function takeAnyStore(store: Store) {}
function takeAnyStore(store: GenericStore) {}

// 新写法
function takeAnyStore(store: StoreGeneric) {}

2. 插件类型定义变更：
   • DefineStoreOptions → 改为 DefineStoreOptionsBase（适用于 setup 和 options 两种 store）

declare module 'pinia' {
  export interface DefineStoreOptionsBase<S, Store> {
    debounce?: {
      [k in keyof StoreActions<Store>]?: number
    }
  }
}

3. 插件类型重命名：
   • PiniaStorePlugin → 改为 PiniaPlugin

依赖要求

• @vue/composition-api 必须升级到 1.1.0 或更高版本

npm install @vue/composition-api@latest
# 或
yarn add @vue/composition-api@latest

构建工具适配

Webpack 4 用户注意事项

使用 Webpack 4（如 Vue CLI）可能会遇到 ESM 模块错误，解决方案：

1. Vue CLI 4.x 用户：
   • 推荐升级所有依赖
   • 或修改 vue.config.js：

module.exports = {
  configureWebpack: {
    module: {
      rules: [
        {
          test: /\.mjs$/,
          include: /node_modules/,
          type: 'javascript/auto',
        },
      ],
    },
  },
}

2. 自定义 Webpack 配置：
   • 添加对 .mjs 文件的支持

module.exports = {
  module: {
    rules: [
      {
        test: /\.mjs$/,
        include: /node_modules/,
        type: 'javascript/auto',
      },
    ],
  },
}

开发工具

Pinia v2 需要 Vue Devtools v6 版本支持，请确保安装最新 beta 版开发工具。

Nuxt 集成

Pinia v2 提供了专门的 Nuxt 模块：

1. 安装新包：

npm install @pinia/nuxt
# 或
yarn add @pinia/nuxt

2. 更新配置：

// nuxt.config.js
module.exports {
  buildModules: [
    '@nuxtjs/composition-api/module',
    '@pinia/nuxt', // 注意包名变更
  ],
}

3. TypeScript 用户更新 tsconfig.json：

{
  "types": [
    "@pinia/nuxt"
  ]
}

迁移后验证

完成上述变更后，建议：

1. 全面运行测试用例
2. 检查所有 store 的功能是否正常
3. 验证插件是否按预期工作
4. 确保开发工具能够正确显示 store 信息

总结

Pinia v2 的迁移过程主要涉及 API 命名变更、类型系统调整和构建配置更新。通过遵循本指南，您可以系统性地完成迁移工作，同时享受 v2 版本带来的新特性和改进。如果在迁移过程中遇到特殊问题，建议查阅 Pinia 的官方文档获取最新信息。