uni.setStorageSync存不下1MB对象主因非API上限,而是平台单key字符串长度限制(如微信小程序1MB)及JSON.stringify后体积暴增;超100KB应改用uni.setStorage+文件系统。

uni.setStorageSync 存不下 1MB 对象?不是上限问题,是用法错位
uni.setStorageSync 没有独立的“存储上限”,它和 uni.setStorage 共享同一套底层机制(如 iOS 的 NSUserDefaults、Android 的 SharedPreferences 或 SQLite),真正卡住你的从来不是 API 本身,而是平台对单 key 字符串长度的硬限制 + 序列化后体积暴增。
常见错误现象:uni.setStorageSync('cart', cartItems) 直接传数组,没报错但读出来是 undefined;或者存完再查 uni.getStorageInfoSync().currentSize 突然涨了 3MB,接着下一次写就静默失败——这通常是因为你把带图片 base64、日志堆栈、完整表单数据一股脑 JSON.stringify 进去了。
- 微信小程序单 key 最大 1MB,超限直接
setStorageSync:fail system error,不抛 JS 异常 - iOS 端对 NSUserDefaults 写入过长字符串会静默截断,且
getStorageSync返回空字符串而非报错 - Android 部分厂商 ROM(如 MIUI)在频繁写入后
currentSize显示为 0,但实际数据还在,导致你误判“还有空间” - JSON.stringify 后体积可能翻倍:Date 对象变 ISO 字符串、undefined 变 null、循环引用直接报错(但部分平台静默失败)
超过 100KB 就别碰 uni.setStorageSync,改用 uni.setStorage + 文件系统
这不是建议,是真机实测结论:只要序列化后字符串 > 100KB,iOS 微信小程序就大概率触发“脚本执行超时”警告,Android 低端机主线程卡顿明显。这时候必须切到异步路径,并把大块数据移出 storage。
- 对象中含 base64 图片、录音 blob、HTML 片段?立刻用
uni.getFileSystemManager().writeFile写入uni.env.USER_DATA_PATH,只把文件路径存进 storage - 用户行为日志、离线消息队列这类滚动数据,用
uni.setStorage存,但每次写前先uni.getStorage读出旧数组,.slice(-100)截取最新 100 条再存,避免无限膨胀 - 需要多端一致读写的配置项(如主题、语言),仍可用
uni.setStorageSync,但必须控制在 10KB 内,且提前JSON.stringify(obj).length校验 - 别依赖
uni.getStorageInfoSync().currentSize做容量预判——它不统计文件系统内容,也不包含uni.downloadFile下载的临时文件,纯看它等于盲开油门
uni.setStorageSync 读不到值?先盯住这三个地方
90% 的“存了读不出”问题跟上限无关,而是环境或调用时机踩坑。
-
key大小写或空格不一致:比如存的是'UserInfo',读的是'userinfo',H5 和小程序都严格区分 - 跨端误读:App 端存的
uni.setStorageSync('token', ...),H5 端用localStorage.getItem('token')肯定为空——uni-app 各端 storage 完全隔离 - 异步写同步读:用
uni.setStorage存完立刻调uni.getStorageSync,尤其在 onLaunch 或 onLoad 里,低性能设备上大概率读到旧值或undefined - 没处理 JSON.parse 失败:
JSON.parse(uni.getStorageSync('data'))如果 storage 里是空字符串或损坏 JSON,直接抛 JS 异常中断后续逻辑
清缓存时 uni.clearStorageSync() 是核按钮,别让它误爆关键数据
上线项目里最危险的不是存不下,而是清得太干净。很多团队在 onLaunch 里加了自动清理逻辑,结果用户重启 App 就丢收藏、丢草稿、丢最后编辑位置。
- 登出时只删明确 key:
uni.removeStorageSync('token')、uni.removeStorageSync('userInfo')、uni.removeStorageSync('refreshToken') - 别用
uni.clearStorageSync()清整个空间——vuex-persistedstate、pinia-plugin-persistedstate 插件也走同一套 storage,一清全没 - 如果用了
uni.downloadFile,它的文件默认存在平台 tmp 目录,uni.clearStorageSync完全不影响,得自己用uni.getFileSystemManager().readdir扫描并清理 - Android 上
uni.clearStorageSync后,uni.getStorageInfoSync().keys可能延迟几秒才更新,别拿它做即时判断依据
真正难的不是“怎么存更多”,而是“哪些不该往 storage 里塞”。base64 图片、离线包、用户生成的大文本,这些从一开始就不该走 uni.setStorageSync。路径、索引、轻量元数据才是它该干的活。一旦越界,问题就从“存不下”变成“读不准”“清不净”“跨端不一致”。


















