# 迁移：异步请求 API ## 目的教授 Next.js 16 中的重大更改，其中请求 API 现在是异步的。这会影响 `params`、`searchParams`、`cookies()`、`headers()` 和 `draftMode()` - 现在都返回 Promises 并需要 `await`。 ## 何时使用 * 从 Next.js 15 迁移到 16 * 修复有关 Promise 类型的 TypeScript 错误 * 使用路由参数、搜索参数或请求标头 * 遇到“对象可能未定义”错误 * 更新服务器组件或API路由 ## 重大变更概述 ### API 现在异步 1. **路由参数（`params`）** * Pages：`params` 属性现在是一个 Promise * 布局：`params` 属性现在是一个 Promise * 路由处理程序：“params”参数现在是一个 Promise 2. **搜索参数（`searchParams`）** * 页面 `searchParams` 属性现在是一个 Promise 3. **请求API** * `cookies()` 返回 Promise * `headers()` 返回 Promise * `draftMode()` 返回 Promise ### 类型更改从“next/headers”导入{cookies、headers、draftMode}；类型 CookiesReturn = Promise; 类型 HeadersReturn = Promise; 类型 DraftModeReturn = Promise<{ isEnabled: boolean }>; ## 迁移模式 ### 模式 1：页面路由参数 **之前（Next.js 15）：** 导出默认函数 Page({ params }: { params: { id: string } }) { return

用户 ID: {params.id}

; } 导出异步函数generateMetadata({ params }: { params: { id: string } }) { return { title: `用户 ${params.id}` }; } **之后（Next.js 16）：** 导出默认异步函数 Page({ 参数 }：{ 参数： Promise<{ id: string }> }) { const { id } = 等待参数； return

用户ID: {id}

; } 导出异步函数generateMetadata({ 参数 }：{ 参数： Promise<{ id: string }> }) { const { id } = 等待参数； return { title: `用户 ${id}` }; } ### 模式 2：搜索参数 **之前（Next.js 15）：** 导出默认函数SearchPage({ 搜索参数 }：{ searchParams: { q?: 字符串;页？：字符串 } }) { const 查询 = searchParams.q || ''; const page = Number(searchParams.page) || 1; 返回 ; } **之后（Next.js 16）：** 导出默认异步函数 SearchPage({ 搜索参数 }：{ searchParams: Promise<{ q?: string;页？：字符串 }> }) { const params = 等待 searchParams； const 查询 = params.q || ''; const page = Number(params.page) || 1; 返回 ; } ### 模式 3：Cookies API **之前（Next.js 15）：** 从'next/headers'导入{cookies}；导出默认函数 Component() { const cookieStore = cookies(); const token = cookieStore.get('token'); 返回

Token: {token?.value}

; } **之后（Next.js 16）：** 从'next/headers'导入{cookies}；导出默认异步函数 Component() { const cookieStore = 等待 cookies(); const token = cookieStore.get('token'); 返回

Token: {token?.value}

; } ### 模式 4：标头 API **之前（Next.js 15）：** 从 'next/headers' 导入 { headers }；导出默认函数 Component() { const headersList = headers(); const userAgent = headersList.get('用户代理'); 返回

用户代理：{userAgent}

； } **之后（Next.js 16）：** 从 'next/headers' 导入 { headers }；导出默认异步函数 Component() { const headersList = 等待 headers(); const userAgent = headersList.get('用户代理'); 返回

用户代理：{userAgent}

； } ### 模式 5：草稿模式 **之前（Next.js 15）：** 从'next/headers'导入{draftMode}；导出默认函数 Component() { const { isEnabled } = DraftMode(); return

草稿模式：{isEnabled ? '开'：'关'}

; } **之后（Next.js 16）：** 从'next/headers'导入{draftMode}；导出默认异步函数 Component() { const { isEnabled } = 等待 DraftMode(); return

草稿模式：{isEnabled ? '开'：'关'}

; } ### 模式 6：路由处理程序 **之前（Next.js 15）：** 导出异步函数 GET( 请求：请求， { 参数 }: { 参数: { id: 字符串 } } ）{ const headersList = headers(); const auth = headersList.get('授权'); 返回 Response.json({ id: params.id, auth }); } **之后（Next.js 16）：** 导出异步函数 GET( 请求：请求， { params }: { params: Promise<{ id: string }> } ）{ const [{ id }, headersList] = 等待 Promise.all([ 参数，标题（） ]); const auth = headersList.get('授权'); 返回 Response.json({ id, auth }); } ### 模式 7：带参数的布局 **之前（Next.js 15）：** 导出默认函数Layout({ 孩子们，参数 }：{ 孩子：React.ReactNode；参数：{区域设置：字符串}； }) { 返回（ {孩子} ）； } **之后（Next.js 16）：** 导出默认异步函数布局({ 孩子们，参数 }：{ 孩子：React.ReactNode； params: Promise<{ locale: string }>; }) { const { locale } = 等待参数；返回（ {孩子} ）； } ## 常见迁移错误 ### 错误1：缺少等待 const { id } = 参数； **修复：** const { id } = 等待参数； ### 错误 2：非异步函数导出默认函数 Page({ params }: { params: Promise<{ id: string }> }) { const { id } = 等待参数； } **修复：** 导出默认异步函数 Page({ params }: { params: Promise<{ id: string }> }) { const { id } = 等待参数； } ### 错误3：类型注释错误导出默认异步函数 Page({ params }: { params: { id: string } }) { const { id } = 等待参数； } **修复：** 导出默认异步函数 Page({ params }: { params: Promise<{ id: string }> }) { const { id } = 等待参数； } ### 错误4：直接访问属性 const cookieStore = 等待 cookies(); const allCookies = cookieStore.getAll(); **修复（相同，但确保在 cookies() 上等待）：** const cookieStore = 等待 cookies(); const allCookies = cookieStore.getAll(); ## 性能优化 ### 使用 Promise.all 进行多个异步调用 **效率低下（顺序）：** const { id } = 等待参数； const 搜索 = 等待搜索参数； const cookieStore = 等待 cookies(); const headersList = 等待 headers(); **优化（并行）：** const [{ id }, 搜索, cookieStore, headersList] = 等待 Promise.all([ 参数，搜索参数，饼干（），标题（） ]); ### 何时使用顺序与并行 **顺序（存在依赖关系）：** const { id } = 等待参数； const data = 等待 fetchData(id); **并行（无依赖性）：** const [{ id }, cookieStore] = 等待 Promise.all([ 参数，饼干（） ]); ## 类型安全 ### 定义可重用类型类型 PageParams = Promise; 类型 SearchParams = Promise<{ [key: string]: string |字符串[] |未定义}>; 类型 PageProps = { 参数：PageParams；搜索参数：搜索参数； }; 导出默认异步函数 Page({ params, searchParams }: PageProps<{ id: string }>) { const { id } = 等待参数； const 搜索 = 等待搜索参数；返回

{id}

; } ### 带有 Promise 的类型保护有关高级 Promise 类型处理和类型防护，请参阅“@typescript/TYPES-type-guards”技能。函数 isValidId(id: string): id 是 string { 返回 /^[a-z0-9]+$/i.test(id); } 导出默认异步函数 Page({ 参数 }：{ 参数： Promise<{ id: string }> }) { const { id } = 等待参数； if (!isValidId(id)) { return

ID 无效

; } return

有效ID：{id}

; } ## 特殊情况 ### 多段路线导出默认异步函数 Page({ 参数 }：{ params: Promise<{ 类别: 字符串;产品：字符串}> }) { const { 类别，产品 } = 等待参数；返回（

类别：{类别}

产品：{产品}

）； } ### 涵盖所有路线导出默认异步函数 Page({ 参数 }：{ params: Promise<{ slug: string[] }> }) { const { slug } = 等待参数； const 路径 = slug.join('/'); 返回

路径：{path}

； } ### 可选的全部路由导出默认异步函数 Page({ 参数 }：{ 参数： Promise<{ slug?: string[] }> }) { const { slug } = 等待参数；如果（！slug）{ 返回

首页

； } 返回

路径：{slug.join('/')}

; } ## 参考文献有关详细的迁移示例、边缘情况和故障排除，请参阅： * [详细异步模式参考]() * Next.js 16 迁移指南： * `@typescript/TYPES-type-guards` 用于 Promise 类型处理 ## 迁移清单迁移到异步请求 API 时： 1. 将所有 `params` 属性更新为 `Promise` 类型 2. 将所有 `searchParams` 属性更新为 `Promise` 类型 3. 将 `await` 添加到所有 `cookies()` 调用中 4. 将 `await` 添加到所有 `headers()` 调用中 5. 将 `await` 添加到所有 `draftMode()` 调用中 6. 根据需要将组件转换为异步 7.更新类型注解 8. 使用 Promise.all 进行多个异步调用 9. 测试所有动态路由 10.测试所有API路由 11.验证TypeScript编译 12. 运行生产构建以捕获错误 ## 成功标准 * 没有与 Promise 类型相关的 TypeScript 错误 * 所有动态路由均正常工作 * 所有API路由正确处理参数 * Cookie、标头和草稿模式按预期工作 * 没有关于“对象可能未定义”的运行时错误 * 构建成功完成

迁移异步请求 API

包含技能