动态 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 代码模组可以自动修复许多此类情况

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

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

如果警告发生在服务器端（例如，路由处理器或服务器组件），你必须 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 代码模组发现任何无法通过代码模组迁移的内容，它将留下带有 @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 强制迁移

如果你没有处理以 @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 静态渲染页面的更多部分。