NNext.js 中文网 GitHub

loading.js

loading.js 文件的 API 参考。

特殊文件 loading.js 可帮助你使用 React Suspense 创建有意义的加载 UI。通过此约定,当路由段的内容流式传入时,你可以从服务器显示即时加载状态。新内容完成后会自动替换进来。

app/feed/loading.tsx
export default function Loading() {
  // 或自定义的加载骨架组件
  return <p>Loading...</p>
}
app/feed/loading.js
export default function Loading() {
  // 或自定义的加载骨架组件
  return <p>Loading...</p>
}

在 loading.js 文件中,你可以添加任何轻量级的加载 UI。你可能会发现使用 React Developer Tools 手动切换 Suspense 边界很有帮助。

默认情况下,此文件是 Server Component,但也可以通过 "use client" 指令用作 Client Component。

参考#

参数#

加载 UI 组件不接受任何参数。

行为#

导航#

  • Fallback UI 会被预取,使导航立即进行,除非预取尚未完成。
  • 导航是可中断的,这意味着更改路由时无需等待当前路由内容完全加载即可导航到另一个路由。
  • 当新路由段加载时,共享的 layout 保持可交互。

即时加载状态#

即时加载状态是在导航时立即显示的 fallback UI。你可以预渲染加载指示器,如骨架和旋转图标,或未来界面的一个小但有意义的部分,如封面照片、标题等。这有助于用户理解应用正在响应,并提供更好的用户体验。

通过在文件夹中添加 loading.js 文件来创建加载状态。

app/dashboard/loading.tsx
export default function Loading() {
  // 你可以在 Loading 中添加任何 UI,包括 Skeleton。
  return <LoadingSkeleton />
}
app/dashboard/loading.js
export default function Loading() {
  // 你可以在 Loading 中添加任何 UI,包括 Skeleton。
  return <LoadingSkeleton />
}

在同一文件夹中,loading.js 将嵌套在 layout.js 内。它会自动将 page.js 文件及其下方的所有子级包裹在 <Suspense> 边界中。

在组件层级中,loading.js 会将 not-found.js、page.js 和嵌套的 layout.js 文件包裹在 <Suspense> 边界中。它不会包裹同一段中的 layout.js、template.js 或 error.js。

小知识:如果 layout 访问未缓存或运行时数据(例如 cookies()、headers() 或未缓存的 fetch),loading.js 不会为其显示 fallback。

  • 不使用 Cache Components: 导航会阻塞,直到 layout 完成渲染。
  • 使用 Cache Components: layout 中的未缓存或运行时数据访问必须显式包裹在 <Suspense> 中,否则 Next.js 会通过构建时错误引导你。静态 shell 先流式传输,未缓存的内容随后填充。

为确保即时导航,请将未缓存的数据获取从 layout.js 移到 page.js 中,或者将 layout 中的运行时数据访问包裹在其自己的 <Suspense> 边界中。有关详细信息和示例,请参阅 layout.js 注意事项。

SEO#

  • 对于只抓取静态 HTML、无法像完整浏览器那样执行 JavaScript 的机器人(如 Twitterbot),Next.js 会在流式传输 UI 之前解析 generateMetadata,并将元数据放置在初始 HTML 的 <head> 中。
  • 否则,可以使用流式元数据。Next.js 会自动检测用户代理,以在阻塞和流式行为之间选择。
  • 由于流式传输是服务器渲染的,因此不会影响 SEO。你可以使用 Google 的富媒体搜索结果测试(Rich Results Test)工具查看你的页面在 Google 网络爬虫中的显示方式,并查看序列化的 HTML(来源)。

状态码#

流式页面响应以 200 状态码开始。

初始响应头为响应的其余部分设置状态。然后 Next.js 可以使用 redirect、notFound、forbidden 或 unauthorized 流式传输重定向和 HTTP 访问 fallback。

小知识: 使用 Cache Components 时,Next.js 会先发送预渲染的 shell,以及预加载 CSS、字体和图像等资源的请求头。发送 shell 会以 200 开始响应,即使 shell 没有可见的 UI。

例如,当 404 页面流式传输到客户端时,Next.js 会在流式 HTML 中包含一个 <meta name="robots" content="noindex"> 标签。即使 HTTP 状态为 200,这也会阻止搜索引擎索引该 URL。请参阅 Google 关于 robots meta 标签的指南。

有关更多背景信息,请参阅流式传输是否会影响 SEO 以及流式内容是否可以被索引?和Google 如何在整个索引过程中处理 JavaScript。

一些爬虫可能会将这些响应标记为“软 404”。noindex 标签会使它们不出现在搜索结果中。

在流式传输开始之前运行相应的检查,以返回 404、403 或 401 状态,用于合规或分析。

对于 404,你可以在 Proxy 中检查 slug,然后将其重写为 not-found 路由或返回 404 响应。保持 Proxy 检查快速,避免在那里获取完整内容。

<details> <summary>何时开始流式传输?</summary>

开始流式传输会发送请求头并确定状态码。

不使用 Cache Components 时,渲染来自 loading.js 或 <Suspense> 的 fallback 会开始流式传输。如果两者都尚未启动响应,当相应的中断运行时,Next.js 仍可以返回 404、403 或 401。

使用 Cache Components 时,如果中断在预渲染期间(响应开始之前)运行,它可以保留其状态。页面内的请求时检查在 shell 发送之后运行,即使 shell 为空且路由设置了 instant = false,因此状态仍为 200。

</details>

浏览器限制#

某些浏览器会缓冲流式响应。在响应超过 1024 字节之前,你可能看不到流式响应。这通常只影响“hello world”应用,而不影响真实应用。

平台支持#

部署选项是否支持
Node.js server是
Docker container是
Static export否
Adapters取决于平台

了解在自托管 Next.js 时如何配置流式传输。

示例#

使用 Suspense 进行流式传输#

除了 loading.js,你还可以为自己的 UI 组件手动创建 Suspense 边界。App Router 支持使用 Suspense 进行流式传输。有关流式传输的工作原理,包括细粒度的 Suspense 模式、Route Handler 流式传输和基础设施注意事项,请参阅流式传输指南。

<Suspense> 的工作原理是包裹一个执行异步操作(如获取数据)的组件,在操作进行时显示 fallback UI(如骨架、旋转图标),然后在操作完成后换入你的组件。

app/dashboard/page.tsx
import { Suspense } from 'react'
import { PostFeed, Weather } from './Components'

export default function Posts() {
  return (
    <section>
      <Suspense fallback={<p>Loading feed...</p>}>
        <PostFeed />
      </Suspense>
      <Suspense fallback={<p>Loading weather...</p>}>
        <Weather />
      </Suspense>
    </section>
  )
}
app/dashboard/page.js
import { Suspense } from 'react'
import { PostFeed, Weather } from './Components'

export default function Posts() {
  return (
    <section>
      <Suspense fallback={<p>Loading feed...</p>}>
        <PostFeed />
      </Suspense>
      <Suspense fallback={<p>Loading weather...</p>}>
        <Weather />
      </Suspense>
    </section>
  )
}

使用 Suspense,你将获得以下好处:

  1. 流式服务器渲染——从服务器到客户端逐步渲染 HTML。
  2. 选择性水合(Hydration)——React 根据用户交互确定优先让哪些组件首先具有交互性。

有关更多 Suspense 示例和用例,请参阅 React 文档。

版本历史#

版本变更
v13.0.0引入 loading。
Next.js 中文网