navigator.onLine 监听网络变化并触发同步

本文深入剖析了 `navigator.onLine` 的本质局限——它仅是一个静态、粗略的系统级网络快照，既不能触发同步动作，也无法准确反映真实服务可达性；真正可靠的离线同步必须构建在 `offline`/`online` 事件驱动、本地持久化暂存（如 localStorage 或 IndexedDB）、幂等重试机制及主动初始校验的基础之上，同时需警惕“假在线”陷阱、请求超时、任务时效性等现实问题，才能让 Web 应用在复杂网络环境下稳健实现数据不丢失、不重复、不错发。

navigator.onLine 本身不触发数据同步，它只提供一个粗略的“系统级在线/离线”快照；真正要实现离线任务的数据同步，必须配合 offline 事件 + 本地持久化 + online 事件触发重试，且不能依赖 navigator.onLine 的初始值做同步决策。

为什么不能直接用 navigator.onLine === false 触发同步？

因为 navigator.onLine 是只读属性，它不会“变成 false”来通知你该同步了——它只是当前状态。同步动作必须由事件驱动（比如用户提交后存本地、网络恢复后才发出去），而不是靠轮询这个布尔值。

常见错误现象：

• 在 setInterval(() => { if (!navigator.onLine) syncPendingTasks(); }, 5000) 中反复调用同步逻辑，导致重复发送、资源浪费
• 页面加载时 navigator.onLine === true，但实际 API 已不可达，误判为“可同步”，结果请求直接失败
• 把 offline 事件当作“开始同步时机”，其实此时应做的是「暂存」，不是「发送」

正确流程：offline 存本地，online 才发请求

离线任务同步的本质是「延迟执行」，不是「即时响应」。关键动作发生在两个事件里：

• offline 事件中：把待同步任务（如表单数据、日志、草稿）序列化后写入 localStorage 或 IndexedDB，并标记为 pending
• online 事件中：读取所有 pending 任务，逐条用 fetch() 提交；成功后从存储中移除；失败则保留并可加重试计数

示例节选（不依赖框架）：

const PENDING_KEY = 'pending-sync-tasks';

const savePendingTask = (task) => {
  const tasks = JSON.parse(localStorage.getItem(PENDING_KEY) || '[]');
  tasks.push({ ...task, timestamp: Date.now() });
  localStorage.setItem(PENDING_KEY, JSON.stringify(tasks));
};

const trySyncPending = async () => {
  const tasks = JSON.parse(localStorage.getItem(PENDING_KEY) || '[]');
  if (tasks.length === 0) return;

  for (const task of tasks) {
    try {
      await fetch('/api/submit', {
        method: 'POST',
        body: JSON.stringify(task.payload),
        headers: { 'Content-Type': 'application/json' }
      });
      // 成功后过滤掉该 task
      const updated = tasks.filter(t => t !== task);
      localStorage.setItem(PENDING_KEY, JSON.stringify(updated));
    } catch (e) {
      // 失败不中断后续，留待下次 online 再试
      console.warn('sync failed, retry later:', e);
    }
  }
};

window.addEventListener('offline', () => {
  console.log('go offline → pause sync, save pending');
});

window.addEventListener('online', () => {
  console.log('go online → trigger sync');
  trySyncPending();
});

// 页面加载时也检查一次，防止 onload 时已 online 但有遗留 pending
if (navigator.onLine) trySyncPending();

必须手动校验初始 online 状态，否则 pending 会积压

页面启动时，online 事件不会自动触发，哪怕浏览器确实是在线的。如果你只监听事件，就永远不知道“现在能不能发”，也就不会主动去清空 pending 队列。

所以这行代码不能省：

if (navigator.onLine) trySyncPending();

但它有个前提：你得确保 trySyncPending() 是幂等的（多次调用不会重复提交同一任务），否则冷启动时可能把刚存进去的 pending 发两遍。

真实离线场景下，仅靠 navigator.onLine 不够可靠

比如用户连着 WiFi，但 DNS 被劫持、网关宕机、或公司防火墙拦截了你的域名——此时 navigator.onLine 仍是 true，但所有 fetch() 都会失败。这种“假在线”会导致 pending 积压却无感知。

建议增强方式：

• 在 trySyncPending() 中对每个请求加 AbortSignal.timeout(5000)
• 若连续 3 次请求都因网络原因失败（TypeError: Failed to fetch），主动触发一次 dispatchEvent(new Event('real-offline'))，让 UI 层降级显示提示
• 避免把同步逻辑和 UI 提示耦合在同一个事件里；online 只管发，real-offline 只管提示

最易被忽略的一点：同步任务本身可能包含时间敏感字段（如 token 过期、订单时效），存进 localStorage 前要检查有效期，而不是无脑存、无脑发。

终于介绍完啦！小伙伴们，这篇关于《navigator.onLine 监听网络变化并触发同步》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！