uni-app怎么使用Pinia管理状态-uni-app-PHP中文网

应装 @dcloudio/pinia 或使用 HBuilderX ≥ 4.14 内置版本；HBuilderX ≥ 4.14 直接 import { createPinia } from 'pinia'，旧版或 CLI 项目必须 npm install @dcloudio/pinia。

uni-app怎么使用pinia管理状态

不能直接装官方 pinia，必须用 @dcloudio/pinia 或 HBuilderX ≥ 4.14 内置版本，否则小程序编译失败、H5 报 app.use is not a function、App 端白屏——这是最常踩的坑，不是配置问题，是包本身不兼容。

该装哪个包？看你的开发环境

装错包，后面所有步骤都白搭：

HBuilderX ≥ 4.14：无需安装，import { createPinia } from 'pinia' 可直接用（它内部已 alias 到 @dcloudio/pinia）
HBuilderX npm install @dcloudio/pinia，别写 pinia，也别加 @2.x 版本号
旧项目升级到 HBuilderX 4.14+：必须整包更新，禁用 .wgt 热更新，否则低版本基座加载高版本 Pinia 会报 Cannot read property 'isMounted' of undefined

main.js 初始化顺序不能错

uni-app 不走 app.use(pinia) 标准流程，而是靠 uni.$pinia 全局挂载；顺序错或位置错，组件里调用 useXXXStore() 就返回 undefined：

必须在 createSSRApp(App) 之后、return { app } 之前创建实例
createPinia() 不能写在 createApp 函数外（否则 Vue 上下文未就绪）
不能用条件编译包裹 import，比如 /* #ifdef MP-WEIXIN */ import { createPinia } from '@dcloudio/pinia' /* #endif */ —— JS 模块导入不识别条件编译，H5 端直接报 Module not found

正确写法：

import { createSSRApp } from 'vue'
import { createPinia } from '@dcloudio/pinia'
import App from './App.vue'
<p>export function createApp() {
const app = createSSRApp(App)
const pinia = createPinia()
uni.$pinia = pinia // 关键：挂到 uni 实例
return { app, pinia }
}</p>

store 定义和跨端避坑要点

定义方式看着和 Vue 项目一样，但小程序和 App 端 Proxy 支持不全，稍不注意 state 就不响应：

uni-app

uni-app 是基于 Vue 的跨端开发框架，适合开发 H5、App、小程序、鸿蒙和多端业务应用。

下载

state 必须是函数，且返回 plain object，不要用 reactive({}) 包一层，更不要返回 Map、Set 或 class 实例（小程序端响应式失效）
避免在 onLaunch、onShow 等非组件生命周期里直接调用 useXXXStore()，会报 store is not active；需放到页面 onLoad 或 onShow 的 setup 中
如果要用本地缓存，别装 pinia-plugin-persistedstate，它依赖 window.localStorage，小程序不支持；必须用 pinia-plugin-unistorage，并手动传入 uni.getStorageSync 适配器
持久化要按需开启：在 store 定义里加 persist: true（不是 unistorage: true，后者是旧版写法），否则所有 state 都进 storage，影响性能且可能存敏感数据

调试时 store 数据“丢了”？先查这三处

不是 Pinia 坏了，是 uni-app 多端机制导致的隐性行为：

小程序热重载（HMR）后，store 实例重建，但已有页面组件没重新 setup，仍引用旧实例 → 表现为“数据没变”或“修改无效”，强制刷新页面可复现
state 里用了 new Date()、Math.random() 等非响应式值，持久化插件序列化后还原成字符串，再读取时失去类型 → 应该用 ref 显式包装
多个页面同时调用同一个 store 的 action 修改同一字段，但没加锁或防抖 → 小程序端因 JS 执行模型差异，可能出现竞态覆盖

最易被忽略的是：store 文件路径必须在 stores/ 目录下，且导出名必须是 useXXXStore 格式，否则 HBuilderX 的自动类型推导和 devtools 支持会失效。这不是硬性报错，但会让 TS 提示和调试体验断崖式下降。