导读（3行收益）：小程序 wx.setStorage 好用，但越攒越大、老用户包体爆、版本更新后旧数据不兼容。本文给 6 个高频坑与解法：容量上限、key 命名、过期策略、序列化、版本迁移、主动清理，附可直接抄的封装代码。看完本地缓存不再乱。
一、Storage 为什么越攒越乱
三个高发问题：
- 容量超限：单 key 1MB、总 10MB，老用户存满后写入失败；
- 数据过期：缓存的配置、购物车半年后还在，版本更新后逻辑对不上；
- 清理无差别：用户清缓存，关键登录态丢了，重新登录。
根源是把 Storage 当万能数据库，没有分层、过期和版本意识。
二、6 个坑逐个拆
坑1：容量超限直接报错
wx.setStorage({
key: 'large', data: bigData,
fail: (e) => {
if(e.errMsg.includes('exceed')) cleanOld(); } })
- 总上限 10MB、单 key 1MB；
- 写入失败要捕获，不能静默；
- 超限触发清理旧缓存。
避坑：不判断容量直接写——老用户偶发失败；存大对象不压缩——一个 key 吃满。
坑2：key 命名混乱
const K = {
CART:'cart:v1', USER:'user:v1', CFG:'cfg:v1' };
- 统一前缀+版本号（cart:v1）；
- 业务 key 集中管理，不散落字符串；
- 改名时留迁移脚本。
避坑：key 全靠手写——重构时漏改；不带版本号——数据结构升级后读出来 undefined。
坑3：没有过期策略
function setCache(key, data, ttl=3600) {
wx.setStorageSync(key, {
v:1, t:Date.now(), d:data, ttl });
}
function getCache(key) {
const x = wx.getStorageSync(key);
if(!x) return null;
if(Date.now()-x.t > x.ttl*1000) {
wx.removeStorageSync(key); return null; }
return x.d;
}
- 缓存带写入时间和 TTL；
- 读时判断过期，过期即删；
- 配置类短 TTL、用户态长 TTL。
避坑：缓存永不过期——版本更新后旧数据污染；TTL 写死——不同业务混一起。
坑4：序列化直接存对象
// 错误：存 undefined / function / 循环引用
// 正确：只存可 JSON 序列化的数据
const safe = JSON.parse(JSON.stringify(data));
- Storage 只支持字符串/对象，不能存函数、DOM、Map；
- 大对象先 JSON 序列化；
- 循环引用要先解。
避坑：直接存页面实例——读出来是 {}；存 Map/Set——JSON 后变空对象。
坑5：版本更新后旧数据不兼容
// 启动时跑一次
const V = 2;
if(wx.getStorageSync('appVer') !== V) {
wx.removeStorageSync('cart:v1');
wx.setStorageSync('appVer', V);
}
- 本地记 appVer；
- 启动时检测版本，不匹配就清旧 key；
- 关键数据（登录态）单独保留。
避坑：数据结构改了不迁移——老用户白屏；启动不清缓存——新旧字段混读报错。
坑6：清理无差别删
- 分类：登录态、用户偏好、业务缓存、临时数据；
- 只清临时和过期业务缓存；
- 登录态和偏好保留。
避坑：wx.clearStorage 一把梭——用户要重新登录、购物车丢光；不分类全删——差评。
三、分层建议
| 类型 | TTL | 示例 |
|---|---|---|
| 登录态 | 长 | token、userInfo |
| 用户偏好 | 长 | 地址、设置 |
| 业务缓存 | 短 | 配置、列表 |
| 临时数据 | 短 | 表单草稿、图片临时路径 |
四、踩坑清单
- [ ] 不判断容量直接写；
- [ ] key 命名混乱不带版本；
- [ ] 缓存永不过期；
- [ ] 直接存不可序列化对象；
- [ ] 版本更新不迁移；
- [ ] wx.clearStorage 一把梭。
五、工程落地建议
小程序本地缓存建议按「集中 key+TTL 过期+版本迁移+分层清理」落地。若团队用成型小程序平台（如乔拓云轻应用系统）起步，重点核对缓存封装是否带过期与版本判断。
六、复盘清单（可直接抄走）
- [ ] key 是否集中管理带版本；
- [ ] 写入是否捕获容量超限；
- [ ] 缓存是否带 TTL；
- [ ] 启动是否跑版本迁移；
- [ ] 清理是否分类不删登录态。
结语
小程序 Storage 不是越多越好，而是要分层、过期、带版本、能清理。这套做对，老用户不爆、版本更新不脏、清缓存不伤登录态。本文仅作技术分享，具体 API 以微信官方文档实时信息为准。
