
小程序本地存储的结论可以先行明确:storage 是每个小程序独立于代码包的本地缓存,按用户维度隔离,单 key 上限 1MB、同一用户同一小程序总量上限 10MB;数据默认长期可用,只在用户主动删除或代码包被清理时才随之清除;同步接口用于简单读取,异步接口适合体积较大或加密场景。把容量、隔离、清理、同步异步四件事分开看,本地存储的使用边界就清楚了。
一、本地存储是什么:与代码包、服务端的关系
每个微信小程序都有自己的本地缓存,通过 setStorage、getStorage、removeStorage、clearStorage 及其 Sync 版本进行读写与清理。它既不属于代码包,也不等于服务端数据库,三者职责需要区分。
| 存储位置 | 由谁维护 | 典型内容 | 是否会随用户变更 |
|---|---|---|---|
| 代码包 | 微信客户端下载与更新 | 页面、组件、脚本、样式 | 随版本更新替换 |
| 本地缓存 storage | 小程序运行时写入设备 | 配置、标记、临时状态、少量用户偏好 | 按用户隔离,跟随设备 |
| 服务端存储 | 开发者服务端与数据库 | 账号、订单、资产、需要跨端同步的数据 | 与用户账号绑定,跨设备可用 |
本地缓存的定位是”设备上的快速读写层”。它适合保存对实时性要求不高、即使丢失也能重新获取的数据;不适合作为唯一数据源保存账号资产、交易记录或需要跨设备一致的状态。误用本地缓存承载核心数据,是后续出现”换设备数据消失””用户删小程序后状态丢失”一类问题的主要来源。
二、容量上限与数据类型
官方文档对容量有明确数字:单个 key 允许存储的最大数据长度为 1MB,所有数据存储上限为 10MB。若开启加密存储,加密后的数据会比原始数据膨胀约 1.4 倍,单 key 上限降为 0.7MB,总量上限降为 7.1MB。
| 项目 | 未加密 | 开启加密 |
|---|---|---|
| 单个 key 上限 | 1MB | 0.7MB |
| 总量上限 | 10MB | 7.1MB |
| 加密方式 | 不加密 | AES128 |
| 接口支持 | 同步与异步都支持 | 仅异步 setStorage 支持 |
| 基础库要求 | 无额外要求 | 2.21.3 及以上 |
开启加密存储时,setStorage 与 getStorage 需要同时声明 encrypt 为 true,否则读写不匹配。加密会带来额外回调耗时,因此不宜把所有数据默认加密,应按数据敏感度选择。
数据类型方面,setStorage 只支持原生类型、Date、以及能够通过 JSON.stringify 序列化的对象。函数、循环引用的对象、部分内置类型无法正确序列化,写入后读取到的内容可能与预期不符。要在写入前确认数据可以被 JSON.stringify 正常处理,避免”写入成功但读出来是空对象”的情况。

三、隔离规则:用户、小程序与插件三层
storage 以用户维度隔离。同一台设备上,A 用户无法读到 B 用户的数据;不同小程序之间也无法互相读写数据。这一规则同时覆盖小程序与插件之间的边界。
| 场景 | 是否互通 | 说明 |
|---|---|---|
| 同一小程序、同一用户、不同页面 | 互通 | 页面之间共享同一份缓存 |
| 同一小程序、同一设备、不同用户 | 不互通 | 按用户维度隔离 |
| 同一设备、不同小程序 | 不互通 | 小程序之间无法互相读写 |
| 同一小程序使用不同插件 | 不互通 | 插件之间、插件与小程序之间均隔离 |
| 不同小程序使用同一插件 | 不互通 | 同一插件的缓存按小程序隔离 |
隔离规则带来的一个实际影响是:涉及用户身份的本地数据,在账号切换后必须重新读取或清理,不能假设缓存仍然属于当前用户。若把用户与非用户数据混在同一个 key 中缓存,切换账号时容易读到上一个用户的内容。
为了避免这类串数据问题,key 的命名可与用户标识或业务维度关联,或者在识别到账号变化时主动清理用户相关缓存。对于插头小程序场景,还应意识到插件缓存与宿主小程序缓存不共享,不要设计依赖跨端读取的缓存方案。
四、同步与异步接口的选择
本地存储同时提供同步与异步两套接口,差别在于是否阻塞当前调用线程以及是否支持加密。
| 接口 | 方式 | 特点 | 适用 |
|---|---|---|---|
| wx.setStorage / getStorage | 异步 | 通过回调或 Promise 返回结果,支持加密 | 较大数据、需要加密、不阻塞渲染 |
| wx.setStorageSync / getStorageSync | 同步 | 直接返回结果,代码简洁,阻塞当前线程 | 少量简单数据的读写 |
| wx.removeStorage / removeStorageSync | 异步 / 同步 | 删除单个 key | 按需要清理指定缓存 |
| wx.clearStorage / clearStorageSync | 异步 / 同步 | 清空全部缓存 | 退出登录、账号切换等整体清理 |
在页面渲染路径上频繁调用同步接口,会增加主线程负担。初始化阶段一次性读取少量配置用同步接口问题不大;若在列表滚动或高频事件里反复同步读写较大数据,应改为异步并合并读写次数。
另一个易错点是同步接口失败时的处理。同步接口通过异常而非 fail 回调报告错误,若不做异常捕获,容量超限或数据类型非法会直接中断后续逻辑。把本地存储的读写封装成统一工具函数,在其中处理异常与默认值,可以避免每个调用点各写一套判断。
五、key 命名与版本化管理
本地缓存没有目录结构,所有数据都平铺在 key 空间里。随着功能迭代,key 数量容易失控,出现含义不清、重复存储、旧 key 遗留等问题。建立统一的命名规范,是让缓存长期可维护的前提。
| 命名要素 | 示例形式 | 作用 |
|---|---|---|
| 业务域前缀 | 模块名开头 | 区分不同功能,避免跨模块重名 |
| 用户维度 | 包含用户标识或明确标注为公共 | 防止账号切换时串数据 |
| 数据项 | 说明具体内容 | 一眼看出缓存用途 |
| 版本后缀 | 结构变更时递增 | 结构升级时旧 key 自然失效 |
版本后缀的用途在于结构升级。当某个缓存的数据结构发生变化,直接覆盖旧 key 可能让尚未更新的代码读取失败;换用带新版本后缀的 key,则可以让新旧结构并存一段时间,等版本覆盖率上来后再清理旧 key。
配套的清理策略也应写进命名规范:哪些 key 属于用户维度、必须在退出登录时清除;哪些是公共配置、可以长期保留。把这条规则固化成一份清单,比在代码各处临时写 clearStorage 更可控。
六、清理策略与生命周期
官方文档对清理时机的表述很明确:本地缓存的清理时机跟代码包一样,只有在代码包被清理的时候本地缓存才会被清理。在这之前,除非用户主动删除或因存储空间原因被系统清理,否则数据一直可用。
| 触发条件 | 缓存是否清除 | 说明 |
|---|---|---|
| 退出小程序 | 不清除 | 下次进入仍可读取 |
| 发布新版本 | 不清除 | 缓存与代码包版本无关 |
| 用户删除小程序 | 清除 | 代码包被清理时缓存一并清除 |
| 系统因存储空间清理 | 可能清除 | 属于官方列出的清理原因 |
| 调用 clearStorage | 清除 | 开发者主动清空 |
这条规则决定了本地缓存不能被当作永久存储:用户删除小程序、系统回收空间都会导致数据消失。因此从缓存中读到空值时,应有明确的回退路径,例如重新拉取服务端数据或使用默认配置,而不是把空值当作业务上的”无数据”。

七、适合与不适合存入的数据
判断一份数据能否放进本地缓存,可以看三个条件:丢失后能否重新获取、是否只在当前设备有意义、是否愿意接受用户维度的隔离。三个条件都满足,才适合放进 storage。
| 数据类别 | 是否适合 | 理由 |
|---|---|---|
| 界面偏好、主题设置 | 适合 | 丢失可恢复,设备维度即可 |
| 非敏感配置与功能开关 | 适合 | 可随时从服务端重新拉取 |
| 接口返回的临时列表 | 视情况 | 需设置时效并允许回源 |
| 登录凭证与敏感信息 | 谨慎 | 需评估加密与泄露风险 |
| 订单、余额、资产状态 | 不适合作为唯一来源 | 需跨设备一致,以服务端为准 |
| 大体积图片或文件 | 不适合 | 受单 key 与总量上限约束 |
对于临时列表一类的缓存,建议带上时间戳字段,读取时判断是否过期,过期则重新请求服务端。本地缓存没有内建过期机制,”存进去就一直有效”的假设会让用户在几天后仍看到旧数据。
敏感信息方面,即便开启加密存储,也应评估设备本身的安全边界。加密存储解决的是”缓存文件被直接读取”的风险,不能替代服务端对凭证有效期的控制。涉及身份认证的数据,仍应由服务端签发与校验,本地只保留必要的临时结果。
八、缓存与服务端数据的职责边界
本地缓存最常见的误用,是把它当成服务端的替代品。判断是否越界,可以从数据来源、一致性要求、丢失影响三个角度评估。
| 评估角度 | 适合放本地缓存 | 应放服务端 |
|---|---|---|
| 数据来源 | 可从服务端重新获取 | 由服务端产生并维护 |
| 一致性要求 | 允许短时间不一致 | 要求多端实时一致 |
| 丢失影响 | 丢失后可自动恢复 | 丢失会造成业务损失 |
| 共享范围 | 仅当前设备当前用户 | 跨设备、跨用户共享 |
缓存与服务端的合理关系是”服务端为准、缓存加速”。读取时先取缓存并按时间戳判断是否过期,过期则回源更新;写入时先更新服务端,再同步更新缓存。反过来先写缓存再等服务端成功,容易在网络失败时留下与服务端不一致的本地状态。
对于需要展示但不必实时的数据,例如首页配置、字典项、历史搜索词,本地缓存能显著减少请求次数。对于交易与资产类数据,本地最多保存一份用于展示的副本,真正的结果必须每次从服务端获取。
九、失败与异常反查顺序
本地存储出问题通常集中在读不到、写不进、串数据三类。按下表顺序反查,可以较快定位到容量、类型、隔离、生命周期四类根因。
| 现象 | 优先核查项 | 常见原因 |
|---|---|---|
| 写入失败 | 单 key 与总量上限 | 超出 1MB 或 10MB 限制 |
| 写入后读不到 | 数据类型与序列化 | 包含无法 JSON.stringify 的内容 |
| 加密读写不匹配 | encrypt 参数一致性 | 写入与读取未同时声明加密 |
| 换账号读到旧数据 | key 与用户维度的关联 | 账号变化未清理或区分缓存 |
| 删除小程序后数据消失 | 生命周期认知 | 代码包被清理时缓存同步清除 |
| 低端机出现卡顿 | 同步接口调用频次 | 在渲染路径频繁同步读写较大数据 |

十、容量治理与异常处理
缓存写入失败多数与容量有关。总量接近 10MB 时,继续写入会失败;单个数据超过 1MB 时,也会被拒绝。容量治理的目标是让缓存总量长期处于安全范围,而不是等到写入失败再清理。
| 治理手段 | 做法 | 收益 |
|---|---|---|
| 写入前校验 | 估算数据大小,超限则不写或拆分 | 避免直接写入失败 |
| 设置容量阈值 | 总量达到阈值时淘汰旧数据 | 留出写入余量 |
| 大对象拆分 | 把大列表分段存储或改为按需请求 | 规避单 key 上限 |
| 定期清理 | 移除带旧版本后缀与过期的 key | 回收无效占用 |
估算数据大小可以用 JSON.stringify 后的字符串长度作为近似值。对于明显超限的大对象,拆分成多个 key 只是权宜之计,根本办法是不要在缓存中保存大体积内容,改为存标识、用时再向服务端请求。
异常处理要区分”写入失败”和”读取为空”两种情况。写入失败需要捕获异常并决定是否回退到不缓存直接请求的路径;读取为空则可能意味着首次使用、缓存被清理或数据过期,应统一走回源逻辑。两条路径都应有明确日志,便于定位是容量问题还是生命周期问题。
在排查用户反馈时,还需注意”同一现象可能来自不同原因”。例如”数据不见了”既可能是缓存被系统清理,也可能是 key 因结构升级换了版本后缀,还可能是账号切换后读到了新用户维度下的空缓存。区分这三种情况的方法是查看缓存中是否同时存在带不同后缀的旧 key、当前用户标识是否与写入时一致,以及代码中是否有在退出登录时执行的清理动作。把这几项纳入排查清单,比反复让用户”重新进入小程序试试”更能定位根因。
另一个容易被忽略的边界是多端行为差异。同一份代码在微信 Windows 版、Mac 版与鸿蒙 OS 版上运行时,本地缓存的隔离维度仍以用户为准,但不同客户端之间的缓存并不共享。若业务要求”在电脑上设置、在手机上生效”,这类需求应交给服务端处理,而不是期望本地缓存跨端同步。
十一、上线前自检清单
- 核对单 key 不超过 1MB,同一用户总量不超过 10MB
- 若开启加密,确认基础库版本并用同一 encrypt 参数读写
- 写入前验证数据可被 JSON.stringify 正常序列化
- 按用户维度设计 key 或在账号切换时清理用户缓存
- 确认缓存空值有回退路径,不直接等同于业务无数据
- 为临时数据设置时间戳,读取时判断是否过期
- 把同步读写限制在轻量场景,高频路径改用异步
- 封装统一工具函数处理异常,避免每个调用点重复判断
十二、测试与验证方法
本地存储的行为与设备状态、账号、版本都有关系,单靠代码审查难以覆盖全部边界。下面列出几类可以在开发阶段完成的验证,用最小成本提前暴露问题。
| 验证项 | 操作方法 | 预期结果 |
|---|---|---|
| 容量边界 | 分别写入接近与超过上限的数据 | 超限被拒绝且有明确提示 |
| 账号切换 | 写入后切换账号再读取 | 读不到上一个用户的数据 |
| 版本更新 | 更新小程序版本后读取旧缓存 | 缓存仍在,结构变更时能正确迁移 |
| 加密读写 | 开启加密后分别用匹配与不匹配参数读取 | 仅匹配时读到明文 |
在开发者工具中,可通过清除缓存快速模拟”缓存被清理”的场景,验证代码是否走了回源路径。真机上则应至少覆盖一次账号切换与一次版本更新,因为这两类行为在模拟器里与真实环境存在差异。
验证日志需要记录 key、数据大小与操作结果,但不应打印敏感内容。把 key 名称与字节数写进日志,既能定位容量问题,也避免把用户数据暴露在日志系统里。
十三、常见问题
小程序本地存储有效期是多久
默认长期可用,除非用户主动删除、因存储空间被系统清理,或代码包被清理。发布新版本与退出小程序都不会清除缓存。
小程序数据缓存上限是多少
单个 key 上限 1MB,同一用户同一小程序总量上限 10MB。开启加密存储后分别降为 0.7MB 与 7.1MB。
小程序缓存怎么清理
开发者侧可调用 removeStorage 删除单个 key 或 clearStorage 清空全部;用户侧主导的清理方式是删除小程序,代码包清理时缓存一并清除。
小程序本地存储数据放在哪里
写在当前设备的本地缓存中,按用户维度隔离,不同小程序之间不互通,不随账号跨设备同步。
小程序切换账号后读到旧数据怎么办
把 key 与用户标识关联,或在检测到账号变化时清理用户相关缓存,避免不同用户的数据混在同一份缓存里。
小程序 setStorageSync 没有存储成功是什么原因
常见原因是数据超过容量上限、内容无法序列化,或同步接口抛出异常未被捕获。同步接口通过异常报告错误,需要显式处理。
小程序加密存储怎么用
在异步 setStorage 中声明 encrypt 为 true,并在 getStorage 时同样声明。基础库需 2.21.3 及以上,加密后容量上限相应降低。
小程序缓存可以当数据库用吗
不建议。缓存按用户与设备隔离,可能被清理,也不支持跨设备一致。账号、订单、资产等数据应以服务端存储为准。
配图说明:本文部分配图使用人工智能生成合成技术制作。





