跳至內容
文件錯誤動態 API 是非同步的

動態 API 是非同步的

進一步了解為什麼同步存取某些 API 現在會發出警告。

為什麼會出現此警告

您的程式碼中的某處使用了選擇加入動態渲染的 API。

動態 API 是

  • 提供給頁面、佈局、中繼資料 API 和路由處理程式的 params 和 searchParams 屬性。
  • 來自 next/headers 的 cookies()、draftMode() 和 headers()

在 Next 15 中，這些 API 已改為非同步。您可以在 Next.js 15 升級指南中閱讀更多相關資訊。

例如，以下程式碼會發出警告

app/[id]/page.js
function Page({ params }) {
  // direct access of `params.id`.
  return <p>ID: {params.id}</p>
}

這也包含枚舉（例如 {...params} 或 Object.keys(params)）或迭代這些 API 的返回值（例如 [...headers()] 或 for (const cookie of cookies())，或明確使用 cookies()[Symbol.iterator]()）。

在發出此警告的 Next.js 版本中，仍然可以直接訪問這些屬性，但會發出警告。在未來的版本中，這些 API 將會是異步的，直接訪問將無法按預期工作。

可能的修復方法

next-async-request-api 代碼修改器 可以自動修復許多這類情況。

$ npx @next/codemod@canary next-async-request-api .

代碼修改器無法涵蓋所有情況，因此您可能需要手動調整一些代碼。

如果警告發生在伺服器端（例如路由處理程序或伺服器組件），您必須使用 await 等待動態 API 以訪問其屬性。

app/[id]/page.js
function Page({ params }) {
  // asynchronous access of `params.id`.
  const { id } = await params
  return <p>ID: {id}</p>
}

如果警告發生在同步組件中（例如客戶端組件），您必須使用 React.use() 首先解開 Promise。

app/[id]/page.js
'use client'
import * as React from 'react'
 
function Page({ params }) {
  // asynchronous access of `params.id`.
  const { id } = React.use(params)
  return <p>ID: {id}</p>
}

無法遷移的情況 
export function MyCookiesComponent() {
  const c =
    /* @next-codemod-error Manually await this call and refactor the function to be async */
    cookies()
  return c.get('name')
}

使用 Linter 強制遷移

如果您沒有處理代碼修改器留下的以 @next-codemod-error 開頭的註釋，Next.js 將在開發和構建過程中報錯，以強制您解決問題。您可以查看更改並遵循註釋中的建議。您可以進行必要的更改並刪除註釋，或者將註釋前綴 @next-codemod-error 替換為 @next-codemod-ignore。如果沒有任何操作需要執行，註釋前綴 @next-codemod-ignore 將繞過構建錯誤。

- /* @next-codemod-error <suggested message> */
+ /* @next-codemod-ignore */

實用資訊:

您可以延遲解開 Promise（使用 await 或 React.use），直到您實際需要使用該值。這將允許 Next.js 靜態渲染更多頁面內容。