应装 @dcloudio/pinia 或使用 HBuilderX ≥ 4.14 内置版本；HBuilderX ≥ 4.14 直接 import { createPinia } from 'pinia'，旧版或 CLI 项目必须 npm install @dcloudio/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 } }
store 定义和跨端避坑要点
定义方式看着和 Vue 项目一样，但小程序和 App 端 Proxy 支持不全，稍不注意 state 就不响应：
-
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 提示和调试体验断崖式下降。
