useOffline
experimental
了解如何启用实验性的 useOffline 配置选项,以检测连接状态并自动重试失败的请求。
useOffline 配置选项可启用离线连接检测,以及自动重试失败的导航、预取和 Server Action 请求。启用后,它还会暴露 useOffline Hook,用于从 Client Components 读取当前的离线状态。
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: {
useOffline: true,
},
}
export default nextConfigmodule.exports = {
experimental: {
useOffline: true,
},
}启用后,Next.js 将:
- 监听浏览器的
offline和online事件以跟踪连接状态。 - 检测导航、预取和 Server Action 请求中的网络故障。
- 离线时使用
HEAD请求配合退避策略轮询连接状态。 - 连接恢复后自动重试被阻止的请求。
- 使
useOfflineHook 可从next/offline使用。
重试工作机制#
离线状态通过以下两条路径之一进入:
- 浏览器事件。 Next.js 注册一个
window.addEventListener('offline', ...)监听器。当操作系统报告网络接口断开时,离线状态会立即开启。 - 请求失败。 任何导航、预取或 Server Action 请求,如果其
fetch()因非中止、非超时错误而被拒绝,都会调用离线模块。这可以捕获浏览器仍报告navigator.onLine === true,但实际请求无法到达源站的情况(强制门户、DNS 故障、上游宕机)。
进入离线状态后,轮询循环会尝试确认连接是否已恢复。
连接检查#
每次检查都会向当前页面的 URL 发起一个 HEAD 请求,并设置 RSC 请求头,与导航使用的端点相同。请求会在 200 ms 后中止。
有两种结果会被视为“在线”:
fetch正常完成。- 200 ms 超时中止了请求。真正离线的请求几乎会立即失败(DNS 或 TCP 错误),因此如果它在 200 ms 时仍处于挂起状态,说明 TCP 握手已成功,服务器可达。
任何其他拒绝都会安排下一次检查。离线期间成功的框架请求(导航、预取、Server Action)也会将状态切回在线。
退避#
检查之间的延迟是阶梯式的,而非指数式的,且上限为 3 秒:
| 尝试 | 下次检查前的延迟 |
|---|---|
| 1 | 500 ms |
| 2 | 1 s |
| 3 | 2 s |
| 4 及以后 | 3 s |
浏览器的 online 事件会跳过当前等待并立即执行连接检查。无需等待下一个计划时间点即可检测到重新连接。
放弃#
轮询循环自身永不放弃。它会以 3 秒的上限持续运行,直到检查成功或页面卸载。一台设备离线数小时后重新联网,其轮询循环会恢复并正常完成。
框架请求的重试#
在离线状态生效期间,任何导航、预取或 Server Action 都会等待下一次连接检查成功,无论它是新发起的,还是在连接断开时已经在进行中。检查成功后,请求会执行一次;不会应用额外的退避。
如果它因网络错误而失败,应用会重新进入离线状态,轮询循环再次启动。
重新连接时的流量#
单个客户端不会对其源站产生失控的流量爆发:
- 客户端离线时,失败的
fetch()会在浏览器网络层本地被拒绝。请求永远不会到达源站。 - 轮询循环一次只发出一个
HEAD请求,延迟上限为 3 秒。离线期间不会向源站发送其他框架请求。 - 连接恢复时,每个挂起的导航和 Server Action 都会执行一次。只保留最后一次导航尝试为挂起状态,并且典型的表单按钮在其 Action 挂起期间会被禁用。
- 预取通过现有预取队列运行,而非一次性全部执行。
实际上,此功能不太可能压垮你的服务器。每个离线用户产生的唯一额外流量是 HEAD 轮询,连接恢复后即停止。预取、Server Actions 和导航的执行次数与没有中断时相同,只是被延迟了。
版本历史#
| 版本 | 变更 |
|---|---|
v16.x.0 | 新增 experimental.useOffline 配置选项。 |