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

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

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

如果警告发生在服务器上（例如路由处理程序或服务器组件），您必须 `await` 动态 API 才能访问其属性

async 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` 前缀的注释和建议的操作，例如：在这种情况下，您需要手动 await `cookies()` 的调用，并将函数更改为 async。然后重构函数的用法以正确 await

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

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

动态 API 是异步的

为什么出现此警告

可能的解决方法

无法迁移的情况

使用 Linter 强制迁移