Pinia 迁移指南 new

概述

本次升级将项目从 Vuex 迁移至 Pinia，以充分利用 Pinia 在性能、开发体验和生态兼容性上的最新改进。同时，这也是为未来升级到 Vue 3 做的前置准备。

相关链接：

• Demo UI MR
• Overseas MR

核心变更

依赖调整

• 新增依赖："pinia": "^2"
• 移除依赖："vuex"

⚠️ 重要说明

Pinia 暂不支持 Vue 2.7 项目使用 3.x 版本，请务必锁定为 2.x。 使用 3.x 会导致如下错误：

wudi@wudi MINGW64 /c/work/demo-ui (main)
$ pnpm run dev

> @mgcloud/demo-ui@1.0.0 dev C:\work\demo-ui
> vite

project info:
@mgcloud/demo-ui version: 1.0.0, environment: development

  VITE v7.1.5  ready in 1155 ms

  ➜  Local:   http://localhost:8080/
  ➜  Network: http://192.168.120.42:8080/
  ➜  Network: http://192.168.137.1:8080/
  ➜  Network: http://192.168.240.1:8080/
  ➜  Network: http://172.20.48.1:8080/
  ➜  UnoCSS Inspector: http://localhost:8080/__unocss/
  ➜  press h + enter to show help
✘ [ERROR] No matching export in "node_modules/.pnpm/vue@2.7.16/node_modules/vue/dist/vue.esm.js" for import "hasInjectionContext"

    node_modules/.pnpm/pinia@3.0.3_typescript@5.4.5_vue@2.7.16/node_modules/pinia/dist/pinia.mjs:6:9:
      6 │ import { hasInjectionContext, inject, toRaw, watch, unref, markRaw, effectScope, ref, isRef, isReactive, g...
        ╵          ~~~~~~~~~~~~~~~~~~~

C:\work\demo-ui\node_modules\.pnpm\esbuild@0.25.11\node_modules\esbuild\lib\main.js:1467
  let error = new Error(text);
              ^

Error: Error during dependency optimization:

✘ [ERROR] No matching export in "node_modules/.pnpm/vue@2.7.16/node_modules/vue/dist/vue.esm.js" for import "hasInjectionContext"

    node_modules/.pnpm/pinia@3.0.3_typescript@5.4.5_vue@2.7.16/node_modules/pinia/dist/pinia.mjs:6:9:
      6 │ import { hasInjectionContext, inject, toRaw, watch, unref, markRaw,...
        ╵          ~~~~~~~~~~~~~~~~~~~


    at failureErrorWithLog (C:\work\demo-ui\node_modules\.pnpm\esbuild@0.25.11\node_modules\esbuild\lib\main.js:1467:15)
    at C:\work\demo-ui\node_modules\.pnpm\esbuild@0.25.11\node_modules\esbuild\lib\main.js:926:25
    at C:\work\demo-ui\node_modules\.pnpm\esbuild@0.25.11\node_modules\esbuild\lib\main.js:1345:9
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5) {
  errors: [Getter/Setter],
  warnings: [Getter/Setter]
}

Node.js v22.20.0
 ELIFECYCLE  Command failed with exit code 1.

该错误的根因是 pinia@3 依赖 Vue 3 的内部导出，在 Vue 2.7 环境下无法解析。

环境要求

Node.js 版本要求

推荐版本： 当前 Jenkins 测试与生产环境均使用 22.17.1 (LTS)， 建议本地开发环境统一升级至该版本。

关键配置调整

1. Vite define 配置

在 vite.config.js 中增加以下配置：

vite.config.js

import path from 'node:path'
import { defineConfig, loadEnv } from 'vite'
import createVitePlugins from './vite/plugins'

export default defineConfig(({ mode, command }) => {
  const env = loadEnv(mode, process.cwd())

  return {
    // ...其他配置

    plugins: createVitePlugins(env, command === 'build'),
    define: { 
      // This is necessary in Vue 2 codebases. It is automatic in Vue 3
      __VUE_PROD_DEVTOOLS__: 'false', 
    }, 
    resolve: {
      alias: {
        vue: 'vue/dist/vue.esm.js',
        'vue-demi': 'vue-demi/lib/v2.7/index.mjs',
        '@': path.resolve(__dirname, './src'),
      },
      // https://cn.vitejs.dev/config/#resolve-extensions
      extensions: ['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json', '.vue'],
    },
  }
})

2. package.json 依赖更新

package.json

{
  "dependencies": {
    "@mgcloud/lib-base": "1.1.0",
    "@mgcloud/lib-utils": "0.0.10",
    "@mgcloud/pc-base-ui": "0.7.1",
    "@vueuse/core": "^11",
    "aegis-web-sdk": "1.41.1",
    "axios": "0.24.0",
    "core-js": "3.25.3",
    "echarts": "5.5.0",
    "element-ui": "2.15.14",
    "moment": "2.29.1",
    "normalize.css": "7.0.0",
    "nprogress": "0.2.0",
    "path-to-regexp": "2.4.0",
    "pinia": "^2", 
    "sortablejs": "1.10.2",
    "vue": "2.7.16",
    "vue-router": "3.6.5",
    "vuex": "3.6.2"
  }
}

注意事项

1. Pinia 版本锁定： Vue 2.7 项目请务必使用 Pinia 2.x，避免与 Vue 3 内部 API 不兼容。

2. Vue-Demi 兼容性： 若项目依赖 vue-demi，需确保版本支持 Vue 2.7 环境（推荐使用 vue-demi@latest）。

升级步骤

1. 确认 Node.js 版本符合要求
2. 更新 package.json 中的依赖
3. 运行 pnpm install 安装新依赖
4. 更新 vite.config.js 配置
5. 验证项目能正常编译与运行

常见问题

Q: 升级后项目无法启动？
A: 检查 Node.js 版本是否符合要求，并确认 vite.config.js 的 define 配置已添加。

Q: 编译时报错 “hasInjectionContext” 或类似导出缺失？
A: 检查 Pinia 版本，确保为 ^2，不要使用 3.x。

Q: Sass 编译报错？
A: 同样请确认 Pinia 版本号为 2.x，并清除缓存后重新安装依赖。