将 Next.js 14 应用迁移到 Next.js 16 的提示

结构化 AI 代理提示，用于将 Next.js 14 App Router 项目迁移到 Next.js 16，处理破坏性变更并分步进行。

使用此提示来驱动一个谨慎、渐进的 Next.js 14 到 16 迁移——处理异步 params/searchParams API 变更、React 19 对等依赖以及升级前已弃用的 next/headers 模式。

Main Prompt

You are migrating an existing Next.js 14 App Router project to Next.js 16.

Do this in the following ordered steps — do not skip steps or combine them.

Step 1 — Audit (read-only):
  - List every file that uses `params` or `searchParams` as synchronous props.
  - List every file that calls `cookies()`, `headers()`, or `draftMode()` without `await`.
  - List every `next/image` usage with a deprecated prop (e.g., `layout`, `objectFit`).
  - List the current `peerDependencies` for React and React DOM.
  Output the audit as a plain list. Stop and wait for my review.

Step 2 — Update deps:
  - Run: `bun add next@16 react@19 react-dom@19 @types/react@19 @types/react-dom@19`
  - Do NOT change any source files in this step.

Step 3 — Fix async params:
  - For every Page, Layout, and `generateMetadata` function that receives `params` or
    `searchParams`, make the function `async` and `await` the prop before use.
  - Type the props as `Promise<{ slug: string }>` (or the relevant shape), not `{ slug: string }`.

Step 4 — Fix async dynamic APIs:
  - Add `await` before every call to `cookies()`, `headers()`, and `draftMode()`.
  - If the call is inside a non-async function, make that function async.

Step 5 — Fix deprecated Image props:
  - Remove `layout="fill"` and replace with `fill` (boolean).
  - Remove `objectFit` and `objectPosition` props and move them to a `className` or `style`.

Step 6 — Verify:
  - Run `bun run typecheck` and fix all remaining TypeScript errors.
  - Run `bun run build` and confirm exit 0.

After each step, show the diff and wait for confirmation before proceeding.

实现说明

在 Next.js 15+ 中，params 和 searchParams 被 Promise 包裹。同步访问它们会编译通过但在运行时抛出错误——因此在升级前，第一步的审计至关重要。
cookies() 和 headers() 在 Next.js 15+ 中是异步的；最常见的失败模式是在未标记为 async 的函数内部调用它们。
React 19 移除了部分遗留 API（函数组件上的 defaultProps、字符串 refs）。在每个步骤之间运行 bun run typecheck 以尽早发现这些变化。

预期文件更改

package.json                          (edited — next, react, react-dom versions)
bun.lock / package-lock.json          (edited automatically)
src/app/**/page.tsx                   (edited — async params)
src/app/**/layout.tsx                 (edited — async params)
src/app/**/generateMetadata           (edited — async params)
src/components/**/*.tsx               (edited — deprecated Image props)

验收标准

所有步骤完成后，bun run typecheck 退出码为 0。
bun run build 退出码为 0，且无关于已弃用 API 的警告。
所有动态路由在 bun run dev 中正确渲染。
没有同步访问 params 或 searchParams 属性。

测试命令

bun run typecheck
bun run build
bun run dev
# visit several dynamic routes and confirm no runtime errors
grep -r "layout=\"fill\"" src/ && echo "FAIL: deprecated Image prop found"
grep -rn "cookies()\|headers()\|draftMode()" src/ | grep -v "await" && echo "WARN: unawaited dynamic API"

常见 AI 错误

跳过审计步骤并一次性完成所有更改，导致难以追踪的错误。
将异步 params 类型写为 { params: { slug: string } } 而不是 { params: Promise<{ slug: string }> }。
忘记同时升级 @types/react 和 react，导致类型不匹配。
在本身不是异步的嵌套辅助函数内部未对 cookies() 使用 await。

修复提示

The build fails with type errors on params or a runtime error about cookies/headers.
Fix in order:
1. For any page or layout receiving `params`, update the prop type to `Promise<{ slug: string }>` and
   add `const { slug } = await params;` at the top of the function body.
2. Find every call to `cookies()`, `headers()`, `draftMode()` not preceded by `await` and add it.
   Make the containing function async if it isn't already.
3. Run `bun run typecheck` and show me only the remaining errors.

将 Next.js 14 应用迁移到 Next.js 16 的提示

Main Prompt

实现说明

预期文件更改

验收标准

测试命令

常见 AI 错误

修复提示

相关