loading.js

特殊檔案 loading.js 幫助你使用 React Suspense 建立有意義的載入 UI。透過此約定，你可以在路由段的內容流式傳輸時，從伺服器顯示一個即時載入狀態。一旦完成，新內容將自動替換進來。

export default function Loading() {
  // Or a custom loading skeleton component
  return <p>Loading...</p>
}

在 loading.js 檔案中，你可以新增任何輕量級載入 UI。你可能會發現使用 React Developer Tools 手動切換 Suspense 邊界很有幫助。

預設情況下，此檔案是一個伺服器元件——但也可以透過 "use client" 指令用作客戶端元件。

參考

引數

載入 UI 元件不接受任何引數。

行為

回退 UI 會被預取，因此導航會立即進行，除非預取尚未完成。
導航是可中斷的，這意味著更改路由不需要等待路由內容完全載入，即可導航到另一個路由。
共享佈局在新的路由段載入時保持互動性。

即時載入狀態

即時載入狀態是導航時立即顯示的回退 UI。你可以預渲染載入指示器，例如骨架屏和旋轉器，或者未來螢幕的一小部分但有意義的部分，例如封面照片、標題等。這有助於使用者瞭解應用程式正在響應並提供更好的使用者體驗。

透過在資料夾內新增一個 loading.js 檔案來建立載入狀態。

export default function Loading() {
  // You can add any UI inside Loading, including a Skeleton.
  return <LoadingSkeleton />
}

在同一資料夾中，loading.js 將巢狀在 layout.js 內部。它將自動將 page.js 檔案及其下方的任何子級包裝在 <Suspense> 邊界中。

SEO

對於只抓取靜態 HTML 且無法像完整瀏覽器那樣執行 JavaScript 的爬蟲（例如 Twitterbot），Next.js 會在流式 UI 之前解析 generateMetadata，並將元資料放在初始 HTML 的 <head> 中。
否則，可以使用流式元資料。Next.js 會自動檢測使用者代理以選擇阻塞和流式行為。
由於流式傳輸是伺服器端渲染的，因此它不會影響 SEO。你可以使用 Google 的富媒體搜尋結果測試工具，檢視你的頁面在 Google 網頁抓取工具中的顯示方式，並檢視序列化的 HTML（來源）。

狀態碼

當進行流式傳輸時，將返回 200 狀態碼，表示請求成功。

伺服器仍然可以在流式傳輸的內容本身向客戶端傳達錯誤或問題，例如在使用 redirect 或 notFound 時。由於響應頭已經發送到客戶端，因此無法更新響應的狀態碼。

例如，當 404 頁面流式傳輸到客戶端時，Next.js 會在流式傳輸的 HTML 中包含一個 <meta name="robots" content="noindex"> 標籤。這會阻止搜尋引擎索引該 URL，即使 HTTP 狀態為 200。請參閱 Google 關於 robots 元標籤的指南。

一些爬蟲可能會將這些響應標記為“軟 404”。在流式傳輸的情況下，這不會導致索引，因為頁面在 HTML 中明確標記為 noindex。

如果出於合規性或分析目的需要 404 狀態，請確保在響應正文流式傳輸之前資源存在，以便伺服器可以設定 HTTP 狀態碼。

你可以在 proxy 中執行此檢查，將缺失的 slug 重寫為未找到的路由，或者生成 404 響應。請確保代理檢查速度快，並避免在此處獲取完整內容。

響應正文何時流式傳輸？

當 Suspense 回退渲染（例如 loading.tsx）或當伺服器元件在 Suspense 邊界下掛起時，響應正文開始流式傳輸。將 notFound() 放在這些邊界之前以及任何可能掛起的 await 之前。

要開始流式傳輸，必須設定響應頭。這就是為什麼在流式傳輸開始後無法更改狀態碼的原因。

瀏覽器限制

某些瀏覽器會緩衝流式響應。你可能要等到響應超過 1024 位元組後才能看到流式響應。這通常只會影響“Hello World”應用程式，而不會影響實際應用程式。

平臺支援

部署選項	支援
Node.js 伺服器	是
Docker 容器	是
靜態匯出	否
介面卡	平臺特定

瞭解如何配置流式傳輸，當自託管 Next.js 時。

示例

使用 Suspense 進行流式傳輸

除了 loading.js，你還可以手動為自己的 UI 元件建立 Suspense 邊界。App Router 支援使用 Suspense 進行流式傳輸。

<Suspense> 的工作原理是：包裝一個執行非同步操作（例如獲取資料）的元件，在操作進行時顯示回退 UI（例如骨架屏、旋轉器），然後在操作完成後替換為你的元件。

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，你可以獲得以下好處：

流式伺服器渲染 - 逐步將 HTML 從伺服器渲染到客戶端。
選擇性水合 - React 根據使用者互動優先處理哪些元件首先變得可互動。

有關更多 Suspense 示例和用例，請參閱 React 文件。

版本歷史

版本	更改
`v13.0.0`	`loading` 已引入。