小程序离线包与弱网数据同步实战指南 2026

你的页面是读多还是写多？
├─ 读多（列表/详情/配置）
│   └─ 是否允许展示「可能过期」的数据？
│       ├─ 允许 → 方案 2（网络优先 + 缓存兜底）
│       └─ 不允许（强一致，如余额/订单状态）→ 不做缓存，只做超时 + 重试 + 明确错误态
├─ 写多（表单/评论/点赞/埋点）
│   └─ 写操作能否幂等重放？
│       ├─ 能（点赞/收藏/埋点）→ 方案 3（离线队列 + 重连重放）
│       └─ 不能（下单/转账）→ 不做离线，断网即阻断并提示，避免脏提交
└─ 关键二级页（支付页/详情页）→ 叠加方案 5（分包预下载）

// utils/offline-request.js
const CACHE_PREFIX = "offline_cache:";
const QUEUE_KEY = "offline_queue";
const CACHE_TTL = 5 * 60 * 1000; // 读缓存默认 5 分钟

function readCache(key) {
  try {
    const raw = wx.getStorageSync(CACHE_PREFIX + key);
    if (!raw) return null;
    const item = JSON.parse(raw);
    if (Date.now() - item.ts > item.ttl) return null;
    return item.data;
  } catch (e) {
    return null;
  }
}

function writeCache(key, data, ttl = CACHE_TTL) {
  try {
    wx.setStorageSync(CACHE_PREFIX + key, JSON.stringify({ data, ts: Date.now(), ttl }));
  } catch (e) {
    // 超出 10MB 上限时清理最旧缓存后重试一次
    clearOldestCache();
    try {
      wx.setStorageSync(CACHE_PREFIX + key, JSON.stringify({ data, ts: Date.now(), ttl }));
    } catch (e2) { /* 放弃写缓存，不影响主流程 */ }
  }
}

// 读请求：缓存秒开 + 网络刷新
function requestWithCache({ url, method = "GET", data = {}, cacheKey, ttl = CACHE_TTL, timeout = 5000 }) {
  return new Promise((resolve, reject) => {
    const cached = cacheKey ? readCache(cacheKey) : null;
    let settled = false;
    const done = (fn, value) => {
      if (!settled) { settled = true; fn(value); }
    };

    if (cached) resolve(cached); // 秒开，后续网络结果通过 onFresh 回调刷新

    wx.request({
      url,
      method,
      data,
      timeout,
      success(res) {
        if (res.statusCode >= 200 && res.statusCode < 300) {
          if (cacheKey) writeCache(cacheKey, res.data, ttl);
          done(resolve, res.data);
        } else {
          done(cached ? () => {} : reject, new Error(`HTTP ${res.statusCode}`));
        }
      },
      fail(err) {
        if (cached) {
          done(resolve, cached); // 断网兜底
        } else {
          done(reject, err);
        }
      },
    });
  });
}

// 写请求：失败入队，网络恢复后重放（要求幂等）
function enqueueWrite(mutation) {
  const queue = wx.getStorageSync(QUEUE_KEY) || [];
  queue.push({ ...mutation, id: `${Date.now()}_${Math.random().toString(36).slice(2)}` });
  wx.setStorageSync(QUEUE_KEY, queue);
}

function flushQueue() {
  const queue = wx.getStorageSync(QUEUE_KEY) || [];
  if (queue.length === 0) return;
  const task = queue[0];
  wx.request({
    url: task.url,
    method: task.method || "POST",
    data: task.data,
    success(res) {
      if (res.statusCode >= 200 && res.statusCode < 300) {
        wx.setStorageSync(QUEUE_KEY, queue.slice(1)); // 成功移出队首
        flushQueue();
      }
    },
    fail() { /* 网络仍不可用，保留队列，下次再试 */ },
  });
}

module.exports = { requestWithCache, enqueueWrite, flushQueue };

// 乐观更新示例（点赞）
function toggleLike(itemId, liked) {
  const prev = liked;
  updateUI(itemId, !prev); // 先改 UI
  wx.request({
    url: `https://api.example.com/like/${itemId}`,
    method: "POST",
    data: { liked: !prev },
    success() {},
    fail() {
      updateUI(itemId, prev); // 失败回滚
      wx.showToast({ title: "网络异常，请重试", icon: "none" });
    },
  });
}

// app.js 启动时注册
wx.onNetworkStatusChange((res) => {
  if (res.isConnected) {
    flushQueue(); // 网络恢复，重放离线写队列
  }
});

// 弱网（非 wifi/4g/5g 的 2g/3g）时降低图片质量或停用预加载
wx.getNetworkType({
  success(res) {
    if (res.networkType === "2g" || res.networkType === "3g") {
      globalData.weakNetwork = true;
    }
  },
});

{
  "preloadRule": {
    "pages/index/index": {
      "network": "all",
      "packages": ["packageA"]
    }
  }
}

// 版本号失效示例：响应带 version，客户端只在版本变化时回填缓存
function requestVersioned({ url, cacheKey }) {
  const cached = readCache(cacheKey);
  return new Promise((resolve) => {
    wx.request({
      url,
      success(res) {
        const fresh = res.data;
        const staleVersion = cached ? cached.version : undefined;
        if (fresh.version !== staleVersion) {
          writeCache(cacheKey, fresh, CACHE_TTL);
          resolve(fresh);
        } else {
          resolve(cached); // 版本未变，用本地缓存，省一次渲染
        }
      },
      fail() {
        resolve(cached || null); // 断网兜底
      },
    });
  });
}

// utils/storage-adapter.js（uni-app 示例，Taro 同理换 Taro.setStorageSync）
function getStorage(key) {
  // #ifdef MP-WEIXIN
  return wx.getStorageSync(key);
  // #endif
  // #ifdef MP-ALIPAY
  return my.getStorageSync(key);
  // #endif
  // #ifdef MP-TOUTIAO
  return tt.getStorageSync(key);
  // #endif
}

function setStorage(key, value) {
  // #ifdef MP-WEIXIN
  return wx.setStorageSync(key, value);
  // #endif
  // #ifdef MP-ALIPAY
  return my.setStorageSync(key, value);
  // #endif
  // #ifdef MP-TOUTIAO
  return tt.setStorageSync(key, value);
  // #endif
}