NNext.js 中文网 GitHub

useOffline

experimental

了解如何启用实验性的 useOffline 配置选项,以检测连接状态并自动重试失败的请求。

useOffline 配置选项可启用离线连接检测,以及自动重试失败的导航、预取和 Server Action 请求。启用后,它还会暴露 useOffline Hook,用于从 Client Components 读取当前的离线状态。

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    useOffline: true,
  },
}

export default nextConfig
next.config.js
module.exports = {
  experimental: {
    useOffline: true,
  },
}

启用后,Next.js 将:

  • 监听浏览器的 offline 和 online 事件以跟踪连接状态。
  • 检测导航、预取和 Server Action 请求中的网络故障。
  • 离线时使用 HEAD 请求配合退避策略轮询连接状态。
  • 连接恢复后自动重试被阻止的请求。
  • 使 useOffline Hook 可从 next/offline 使用。

重试工作机制#

离线状态通过以下两条路径之一进入:

  • 浏览器事件。 Next.js 注册一个 window.addEventListener('offline', ...) 监听器。当操作系统报告网络接口断开时,离线状态会立即开启。
  • 请求失败。 任何导航、预取或 Server Action 请求,如果其 fetch() 因非中止、非超时错误而被拒绝,都会调用离线模块。这可以捕获浏览器仍报告 navigator.onLine === true,但实际请求无法到达源站的情况(强制门户、DNS 故障、上游宕机)。

进入离线状态后,轮询循环会尝试确认连接是否已恢复。

连接检查#

每次检查都会向当前页面的 URL 发起一个 HEAD 请求,并设置 RSC 请求头,与导航使用的端点相同。请求会在 200 ms 后中止。

有两种结果会被视为“在线”:

  1. fetch 正常完成。
  2. 200 ms 超时中止了请求。真正离线的请求几乎会立即失败(DNS 或 TCP 错误),因此如果它在 200 ms 时仍处于挂起状态,说明 TCP 握手已成功,服务器可达。

任何其他拒绝都会安排下一次检查。离线期间成功的框架请求(导航、预取、Server Action)也会将状态切回在线。

退避#

检查之间的延迟是阶梯式的,而非指数式的,且上限为 3 秒:

尝试下次检查前的延迟
1500 ms
21 s
32 s
4 及以后3 s

浏览器的 online 事件会跳过当前等待并立即执行连接检查。无需等待下一个计划时间点即可检测到重新连接。

放弃#

轮询循环自身永不放弃。它会以 3 秒的上限持续运行,直到检查成功或页面卸载。一台设备离线数小时后重新联网,其轮询循环会恢复并正常完成。

框架请求的重试#

在离线状态生效期间,任何导航、预取或 Server Action 都会等待下一次连接检查成功,无论它是新发起的,还是在连接断开时已经在进行中。检查成功后,请求会执行一次;不会应用额外的退避。

如果它因网络错误而失败,应用会重新进入离线状态,轮询循环再次启动。

重新连接时的流量#

单个客户端不会对其源站产生失控的流量爆发:

  • 客户端离线时,失败的 fetch() 会在浏览器网络层本地被拒绝。请求永远不会到达源站。
  • 轮询循环一次只发出一个 HEAD 请求,延迟上限为 3 秒。离线期间不会向源站发送其他框架请求。
  • 连接恢复时,每个挂起的导航和 Server Action 都会执行一次。只保留最后一次导航尝试为挂起状态,并且典型的表单按钮在其 Action 挂起期间会被禁用。
  • 预取通过现有预取队列运行,而非一次性全部执行。

实际上,此功能不太可能压垮你的服务器。每个离线用户产生的唯一额外流量是 HEAD 轮询,连接恢复后即停止。预取、Server Actions 和导航的执行次数与没有中断时相同,只是被延迟了。

版本历史#

版本变更
v16.x.0新增 experimental.useOffline 配置选项。
Next.js 中文网