第三章 网络状态实时监测

离线优先应用的核心前提是时刻知晓当前网络的可达性与连接质量。仅依赖单一的检测手段往往不可靠，因此需要组合 Navigator.onLine 属性、浏览器原生 online/offline 事件以及应用层心跳检测机制，形成多级、低延迟的感知体系。

3.1 基本原理与权衡

3.2 实现流程

1. 页面加载时读取 navigator.onLine 设置初始状态。
2. 注册 window.addEventListener('online', handler) 和 offline 监听，立刻更新状态并触发业务回调。
3. 启动心跳检测定时器（建议 15-30 秒一次），向服务器或已知端点发送 HEAD/GET 请求，根据响应码或超时判定在线与否。
4. 当事件或心跳检测到状态变化时，更新全局状态机，并存储上次变更时间戳用于日志/分析。
5. 心跳检测结果若与事件状态不一致，以心跳结果为准，并记录脱节次数用于调试。

3.3 核心 API 与代码实现

class NetworkMonitor {
  constructor({
    heartbeatUrl = 'https://example.com/ping',
    heartbeatInterval = 15000,
    timeout = 3000,
    onOnline = () => {},
    onOffline = () => {},
    onStatusChange = () => {}
  } = {}) {
    this.heartbeatUrl = heartbeatUrl;
    this.heartbeatInterval = heartbeatInterval;
    this.timeout = timeout;
    this.onOnline = onOnline;
    this.onOffline = onOffline;
    this.onStatusChange = onStatusChange;
    this._timer = null;
    this._status = navigator.onLine;

    this._bindEvents();
    this._startHeartbeat();
  }

  /** 当前网络状态 */
  get status() { return this._status; }

  /** 绑定浏览器原生事件 */
  _bindEvents() {
    window.addEventListener('online', () => {
      this._updateStatus(true, 'event:online');
    });
    window.addEventListener('offline', () => {
      this._updateStatus(false, 'event:offline');
    });
  }

  /** 心跳检测 - 使用 fetch 与 AbortController 实现超时 */
  async _heartbeat() {
    const controller = new AbortController();
    const id = setTimeout(() => controller.abort(), this.timeout);
    try {
      const res = await fetch(this.heartbeatUrl, {
        method: 'HEAD',
        mode: 'no-cors',  // 跨域场景下仍能检测可达性
        signal: controller.signal
      });
      this._updateStatus(true, 'heartbeat:reachable');
    } catch (err) {
      this._updateStatus(false, 'heartbeat:unreachable');
    } finally {
      clearTimeout(id);
    }
  }

  _updateStatus(newStatus, source) {
    if (newStatus === this._status) return;
    console.log(`[NetworkMonitor] status change: ${newStatus} (${source})`);
    this._status = newStatus;
    this.onStatusChange(newStatus);
    newStatus ? this.onOnline() : this.onOffline();
  }

  _startHeartbeat() {
    this._timer = setInterval(() => this._heartbeat(), this.heartbeatInterval);
  }

  destroy() {
    clearInterval(this._timer);
    window.removeEventListener('online', this._updateStatus);
    window.removeEventListener('offline', this._updateStatus);
  }
}

// 使用示例
const monitor = new NetworkMonitor({
  heartbeatUrl: '/api/ping',
  heartbeatInterval: 20000,
  onOnline: () => { console.log('Ready to sync'); },
  onOffline: () => { console.log('Enter offline mode'); }
});

3.4 体系架构与决策流

3.5 调试与常见错误

3.6 性能与稳定性优化