动态 API 为异步

详细了解为什么同步访问某些 API 现在会发出警告。

出现此警告的原因

在您的代码中的某个地方，您使用了选择加入动态渲染的 API。

动态 API 是

• 提供给页面、布局、元数据 API 和路由处理程序的 params 和 searchParams 属性。
• 来自 next/headers 的 cookies()、draftMode() 和 headers()

在 Next 15 中，这些 API 已变为异步。您可以在 Next.js 15 的升级指南中阅读更多相关内容。

例如，以下代码将发出警告

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 codemod 可以自动修复许多此类情况

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

codemod 无法涵盖所有情况，因此您可能需要手动调整一些代码。

如果警告发生在服务器端（例如路由处理器或服务器组件），则必须 await 动态 API 以访问其属性

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

如果警告发生在同步组件中（例如客户端组件），则必须使用 React.use() 首先解包 Promise

'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>
}

无法迁移的情况

如果 Next.js codemod 发现任何无法通过 codemod 迁移的内容，它将留下一个以 @next-codemod-error 为前缀的注释和建议的操作，例如：在这种情况下，您需要手动等待对 cookies() 的调用，并将函数更改为异步。然后重构函数的使用以使其被正确等待

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 强制迁移

如果您没有处理 codemod 留下的以 @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 静态渲染更多页面内容。