如何监听MapBox地图过期事件？解决次日地图变白问题

核心原因分析 #

你遇到的问题大概率是浏览器闲置标签页的资源回收机制导致的：Chrome、Firefox等浏览器会冻结长时间闲置的标签页，释放WebGL上下文资源，而MapBox依赖WebGL渲染地图，上下文丢失后就会出现白屏。这比API Token或Style过期的可能性高得多——常规MapBox Token是长期有效的，Style缓存也不会在短短一天内失效。

推荐解决方案 #

1. 监听WebGL上下文丢失/恢复事件

直接针对WebGL上下文问题处理，是最精准的方案：

// 获取地图的Canvas元素
const mapCanvas = map.getCanvas();

// 监听上下文丢失事件，阻止默认销毁行为
mapCanvas.addEventListener('webglcontextlost', (event) => {
  event.preventDefault();
  // 可选：显示"地图正在恢复"的提示文案
});

// 上下文恢复时重置地图样式，触发重渲染
mapCanvas.addEventListener('webglcontextrestored', () => {
  map.setStyle(map.getStyle());
});

2. 监听标签页可见性变化

在用户切回标签页时主动检查并修复，避免等到白屏出现：

document.addEventListener('visibilitychange', () => {
  // 当标签页从后台切回前台时
  if (!document.hidden) {
    const glContext = map.getCanvas().getContext('webgl');
    // 检查WebGL上下文是否丢失
    if (glContext && glContext.isContextLost()) {
      map.setStyle(map.getStyle()); // 重置样式恢复渲染
    }
  }
});

3. 优化定时刷新方案（备选）

如果上述事件监听方案无效，再考虑定时刷新，但要避免盲目触发：

let refreshTimer;

// 启动/重置刷新定时器
function setupRefreshTimer() {
  clearTimeout(refreshTimer);
  // 仅当标签页可见时才设置刷新
  if (!document.hidden) {
    refreshTimer = setTimeout(() => {
      window.location.reload();
    }, 12 * 60 * 60 * 1000); // 12小时
  }
}

// 页面加载时初始化定时器
window.addEventListener('load', setupRefreshTimer);
// 标签页切换可见状态时重置定时器
document.addEventListener('visibilitychange', setupRefreshTimer);

额外提示 #

• 如果使用了自定义图层，在map.setStyle()之后可以重新调用图层加载逻辑，确保所有内容恢复。
• error或remove事件通常不会触发WebGL上下文丢失的场景，不用依赖这类事件捕获问题。

内容的提问来源于stack exchange，提问作者Sherri