NNext.js 中文网 GitHub

处理连接中断

experimental

当网络在数据获取或 Server Action 执行过程中断开时,Next.js 应用如何恢复,以及如何将这种状态告知用户。

软导航、数据获取或变更过程中的网络故障会在客户端抛出错误。如果没有显式处理,UI 要么崩溃,要么你必须构建一个要求用户重试的备用 UI。

启用 experimental.useOffline 后,当网络断开时,失败的导航、RSC 数据获取、预取或 Server Action 不再抛出错误。Next.js 会保持其挂起状态,并在连接恢复后重试。

当请求挂起时,UI 处于加载状态(Suspense 回退,或 Server Action 的挂起 transition),这与服务器缓慢时的表现相同。使用 useOffline hook 在应用离线时为用户提供反馈。

你在 Client Component 中使用 fetch() 直接发出的请求,或通过 React Query 或 SWR 等客户端数据库发出的请求,仍遵循该库自身的重试策略。有关框架的检测和轮询行为,请参阅重试的工作方式。

示例#

我们将构建一个实时指标页面,它在每次请求时获取新数据,以及一个调用 Server Action 的 ping 表单。

配套的演示包含此仪表板的两个版本:/without-feedback 使用通用的加载回退,/with-feedback 使用感知连接状态的回退。本指南接下来的部分将逐步介绍如何构建它们。

启用离线检测并查看默认行为#

开启 experimental.useOffline。本指南还启用了 Cache Components 和 Partial Prefetching。Cache Components 使你能够将 Suspense 边界尽可能靠近未缓存的数据放置,并在其周围渲染 App Shell。Partial Prefetching 使该 App Shell 成为 <Link> 预取的单元,因此当离线发生导航时它已准备好渲染。

不使用 Cache Components 时,路由级别的 loading.tsx 可在段级别提供相同的离线行为。请参阅下文的不使用 Cache Components。

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

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

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

你还需要一个带有指向仪表板的 <Link> 的源页面。Next.js 会预取进入视口的任何 <Link> 的 App Shell,正是这种预取使 shell 在离线时可用。

app/page.tsx
import Link from 'next/link'

export default function Home() {
  return (
    <nav>
      <Link href="/dashboard">Dashboard</Link>
    </nav>
  )
}
app/page.js
import Link from 'next/link'

export default function Home() {
  return (
    <nav>
      <Link href="/dashboard">Dashboard</Link>
    </nav>
  )
}

然后构建仪表板本身:一个静态 shell 和 <Suspense> 边界内的未缓存数据部分。getLiveMetrics 是一个未缓存的函数,它向某个端点发出 fetch 请求;每次调用都会访问网络。

app/dashboard/page.tsx
import { Suspense } from 'react'
import { getLiveMetrics } from '../lib/data'

export default function Dashboard() {
  return (
    <section>
      <h1>Live metrics</h1>
      <Suspense fallback={<p>Loading...</p>}>
        <MetricsTable />
      </Suspense>
    </section>
  )
}

async function MetricsTable() {
  const { services } = await getLiveMetrics()
  // 渲染服务
}
app/dashboard/page.js
import { Suspense } from 'react'
import { getLiveMetrics } from '../lib/data'

export default function Dashboard() {
  return (
    <section>
      <h1>Live metrics</h1>
      <Suspense fallback={<p>Loading...</p>}>
        <MetricsTable />
      </Suspense>
    </section>
  )
}

async function MetricsTable() {
  const { services } = await getLiveMetrics()
  // 渲染服务
}

加载首页。当 <Link> 位于视口中时,仪表板的静态 shell 会被预取。进入离线状态(请参阅下文的测试),然后点击进入 /dashboard。

标题和容器从静态 shell 渲染。Loading... 回退会无限期地停留在屏幕上,因为未缓存的 getLiveMetrics() 调用无法完成。用户看到的旋转指示器与服务器缓慢时相同。

切换回在线状态。指标表会自动流式传入。Next.js 自行重试了请求,无需任何客户端代码。

[!NOTE] 此功能仅适用于进入预取路由的软导航和从当前页面发起的 Server Action 调用。离线时的整页重新加载仍会失败,因为浏览器需要网络来传送 HTML;完整的离线加载需要 service worker(请参阅 Progressive Web Apps 指南)。

接下来,将通用的回退 UI 替换为能够读取连接状态的回退 UI。

在 Suspense 回退中报告连接状态#

当浏览器触发 offline 事件或导航、预取或 Server Action 获取失败时,useOffline 返回 true。当后台连接检查成功时,它会翻回 false。这比 navigator.onLine 更可靠,后者仅反映操作系统的网络接口,对于连接到 WiFi 但无法访问互联网的设备仍会报告 true。

创建一个根据该 hook 选择其消息的客户端组件。

app/dashboard/connectivity-fallback.tsx
'use client'

import { useOffline } from 'next/offline'

export function ConnectivityFallback() {
  const isOffline = useOffline()

  return (
    <p>
      {isOffline
        ? 'Waiting for connection to load this section...'
        : 'Loading...'}
    </p>
  )
}
app/dashboard/connectivity-fallback.js
'use client'

import { useOffline } from 'next/offline'

export function ConnectivityFallback() {
  const isOffline = useOffline()

  return (
    <p>
      {isOffline
        ? 'Waiting for connection to load this section...'
        : 'Loading...'}
    </p>
  )
}

[!NOTE] useOffline 在服务端渲染和初始 hydration 期间返回 false。第一个准确的值是应用挂载后浏览器报告的值。

将其作为 Suspense 回退传入。

app/dashboard/page.tsx
import { Suspense } from 'react'
import { getLiveMetrics } from '../lib/data'
import { ConnectivityFallback } from './connectivity-fallback'

export default function Dashboard() {
  return (
    <section>
      <h1>Live metrics</h1>
      <Suspense fallback={<ConnectivityFallback />}>
        <MetricsTable />
      </Suspense>
    </section>
  )
}
app/dashboard/page.js
import { Suspense } from 'react'
import { getLiveMetrics } from '../lib/data'
import { ConnectivityFallback } from './connectivity-fallback'

export default function Dashboard() {
  return (
    <section>
      <h1>Live metrics</h1>
      <Suspense fallback={<ConnectivityFallback />}>
        <MetricsTable />
      </Suspense>
    </section>
  )
}

离线时导航到仪表板,回退现在显示为"Waiting for connection to load this section..."。恢复连接后,指标会随回退消失而流式传入。

该回退仅在此页面显示,且仅在其 Suspense 边界等待时显示。在此应用中,我们在根布局中添加了一个横幅,使连接状态在任何地方都可见。

app/offline-banner.tsx
'use client'

import { useOffline } from 'next/offline'

export function OfflineBanner() {
  const isOffline = useOffline()

  if (!isOffline) {
    return null
  }

  return (
    <div role="status">
      Offline. Pending requests will retry once you are back online.
    </div>
  )
}
app/offline-banner.js
'use client'

import { useOffline } from 'next/offline'

export function OfflineBanner() {
  const isOffline = useOffline()

  if (!isOffline) {
    return null
  }

  return (
    <div role="status">
      Offline. Pending requests will retry once you are back online.
    </div>
  )
}

将其添加到根布局。

app/layout.tsx
import { OfflineBanner } from './offline-banner'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html>
      <body>
        <OfflineBanner />
        {children}
      </body>
    </html>
  )
}
app/layout.js
import { OfflineBanner } from './offline-banner'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <OfflineBanner />
        {children}
      </body>
    </html>
  )
}

离线时,该横幅会在每个路由上显示,连接恢复后隐藏。

对于大多数应用,挂起的加载状态已经足够。在根布局中添加横幅,以便在整个应用中传达连接状态。要在内容加载的位置直接显示该状态,请使用 useOffline 使路由的 Suspense 回退本身能够感知离线状态。

相同的模式也适用于参数化路由。当你离线导航到 /chats/42 时,像 /chats/[id] 这样的路由会渲染其共享的 App Shell,其 <Suspense> 边界后的动态消息会在连接恢复时加载。

如果该路由还在点击之前预取其每个链接的 URL 数据,则 /chats/42 会立即根据该预取渲染其消息,即使离线也是如此,而无需等待连接恢复。请参阅优化预取了解更多信息。

网络恢复后重试 Server Actions#

不使用该标志时,在没有网络的情况下调用 Server Action 会抛出 fetch 错误,且 await 的 promise 会被拒绝。你的表单必须捕获该拒绝并决定如何处理:显示错误、重试或将其排队。

启用 experimental.useOffline 后,该失败永远不会到达你的代码。调用保持挂起,直到连接恢复,请求再次运行,await 的 promise 使用服务端的响应解析。组件中无需 try/catch、无需重试循环、无需重新连接处理程序。

不过,按钮仍会僵在那里。将 useTransition 与 useOffline 结合使用,为其提供感知离线的标签。

app/ping/actions.ts
'use server'

export async function ping(): Promise<string> {
  return new Date().toISOString()
}
app/ping/actions.js
'use server'

export async function ping() {
  return new Date().toISOString()
}
app/ping/ping-form.tsx
'use client'

import { useState, useTransition } from 'react'
import { useOffline } from 'next/offline'
import { ping } from './actions'

export function PingForm() {
  const [pongs, setPongs] = useState<string[]>([])
  const [pending, startTransition] = useTransition()
  const isOffline = useOffline()

  function handleSubmit() {
    startTransition(async () => {
      const pong = await ping()
      setPongs((prev) => [pong, ...prev])
    })
  }

  const label = pending
    ? isOffline
      ? 'Pinging (offline, will retry)...'
      : 'Pinging...'
    : 'Ping'

  return (
    <form action={handleSubmit}>
      <button type="submit" disabled={pending}>
        {label}
      </button>
      <ul>
        {pongs.map((t) => (
          <li key={t}>{t}</li>
        ))}
      </ul>
    </form>
  )
}
app/ping/ping-form.js
'use client'

import { useState, useTransition } from 'react'
import { useOffline } from 'next/offline'
import { ping } from './actions'

export function PingForm() {
  const [pongs, setPongs] = useState([])
  const [pending, startTransition] = useTransition()
  const isOffline = useOffline()

  function handleSubmit() {
    startTransition(async () => {
      const pong = await ping()
      setPongs((prev) => [pong, ...prev])
    })
  }

  const label = pending
    ? isOffline
      ? 'Pinging (offline, will retry)...'
      : 'Pinging...'
    : 'Ping'

  return (
    <form action={handleSubmit}>
      <button type="submit" disabled={pending}>
        {label}
      </button>
      <ul>
        {pongs.map((t) => (
          <li key={t}>{t}</li>
        ))}
      </ul>
    </form>
  )
}

离线时点击 Ping 会禁用按钮,并将其标签更改为"Pinging (offline, will retry)..."。恢复连接后,await 的 ping() 调用会解析,将时间戳附加到列表中,并将标签恢复为"Ping"。无需第二次点击,无需客户端重试代码。

[!NOTE] 离线时,在 Server Action 挂起期间点击链接可能看起来没有任何反应。链接的导航也需要网络,并与该 action 排在相同的连接信号之后。当连接恢复时,两者都会解析。

测试#

使用 next build && next start 测试此功能。开发模式不能可靠地反映离线行为。

在 Chrome 中,使用 DevTools > Network > Offline;在 Firefox 中,使用网络监视器的节流菜单。要进行真实场景测试,请在笔记本电脑或手机上切换飞行模式、断开 WiFi 或拔掉网线。

不使用 Cache Components#

路由级别的 loading.tsx 也能完成同样的工作。它为 Next.js 提供一个边界作为路由的 shell 进行预取,因此 shell 可以离线渲染,网络恢复后页面继续。loading.tsx 预取的工作原理请参阅 Prefetching。useOffline hook、横幅和 Server Action 重试的行为方式都相同。

后续步骤#

Next.js 中文网