应安装 @dcloudio/pinia；官方 pinia 包因依赖标准 SSR 逻辑，在 uni-app 三端运行时报错，HBuilderX 4.14+ 已内置适配版，CLI 项目需手动安装该包。
直接用官方 pinia 包在 uni-app 里会报错，必须用 @dcloudio/pinia 或 hbuilderx 4.14+ 内置版本；持久化也不能套 vue 生态的 pinia-plugin-persistedstate，得换 pinia-plugin-unistorage。
该装哪个 Pinia 包？别踩 pinia 官方包的坑
uni-app 的小程序、App、H5 三端运行时是定制 Vue 运行时，官方 pinia 依赖标准 SSR 逻辑，会导致：
-
createPinia is not a function（H5 白屏或编译失败） -
Cannot read property 'use' of undefined（微信小程序运行时报错） - HBuilderX 4.14+ 已内置适配版，CLI 项目仍需手动安装
@dcloudio/pinia
正确命令：
npm install @dcloudio/pinia
旧版 HBuilderX（pinia@2.0.36，但不推荐新项目用。
main.js 中初始化顺序不能错
Pinia 实例必须在 createSSRApp() 之后、app.use() 之前创建，否则组件内调用 useXXXStore() 会返回 undefined。
错误写法（store 提前声明）：
import { createPinia } from '@dcloudio/pinia'
const pinia = createPinia() // ❌ 此时 Vue 尚未初始化
<p>export function createApp() {
const app = createSSRApp(App)
app.use(pinia) // ❌ pinia 拿不到上下文
return { app }
}正确写法：
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() // ✅ 紧接 createSSRApp 后
app.use(pinia)
return { app, pinia } // 注意：HBuilderX 要求必须返回 pinia
}别用 /* #ifdef MP-WEIXIN */ 包裹 import —— JS 模块导入不走条件编译，H5 端会找不到模块。
Store 文件怎么写？state 必须是函数
直接写对象会导致多页面/多实例下 state 共享，比如从小程序 A 页面跳 B 页面再返回，A 页面的 count 可能被 B 页面改过。
错误写法：
state: { count: 0 } // ❌ 所有实例共用一个对象引用正确写法：
state: () => ({ count: 0 }) // ✅ 每次调用都返回新对象其他注意事项：
-
getters和actions写法和标准 Pinia 一致，支持 TypeScript 类型推导 - 不要在
onLaunch、utils/工具函数中直接调用useXXXStore()，这些地方没有 Vue 组件上下文，会报store is not active - 需要全局触发的逻辑（如登录态恢复），应放在首个页面的
onLoad或onShow中执行
如何让 Store 自动持久化？只对关键字段生效
不是所有状态都该进本地存储，比如 loading、弹窗开关这类临时状态，存了反而拖慢启动速度、污染 storage。
用 pinia-plugin-unistorage + persist 选项精准控制：
npm install pinia-plugin-unistorage
在 main.js 注册插件（注意顺序：必须在 app.use(pinia) 前）：
import piniaPluginUnistorage from 'pinia-plugin-unistorage'
<p>const pinia = createPinia()
pinia.use(piniaPluginUnistorage({
storage: {
getItem: key => uni.getStorageSync(key),
setItem: (key, value) => uni.setStorageSync(key, value),
removeItem: key => uni.removeStorageSync(key)
}
}))然后在具体 store 中启用：
import { defineStore } from '@dcloudio/pinia'
<p>export const useUserStore = defineStore('user', {
state: () => ({
token: '',
userInfo: null,
tempFlag: false // 不想持久化
}),
persist: {
key: 'user-store',
paths: ['token', 'userInfo'] // ✅ 只持久化这两个字段
}
})注意：persist 是插件能力，不是 Pinia 原生 API，没装 pinia-plugin-unistorage 或没正确注册，这个配置就完全无效。
最易忽略的一点：HBuilderX 4.14 升级后，如果之前用 wgt 更新过 App，现在必须整包更新——低版本基座加载高版本 Pinia wgt 会直接报 Cannot read property 'isMounted' of undefined，这不是代码问题，是运行时环境不匹配。
