# 数据层迁移将数据获取模式（getStaticProps、getServerSideProps、getStaticPaths）和 API 路由迁移到 App Router 等效项。 ## 工具包设置此技能需要安装“nextjs-migration-toolkit”技能。所有迁移技能都依赖于它来进行 AST 分析。 TOOLKIT_DIR="$(cd "$(dirname "$SKILL_PATH")/../nextjs-migration-toolkit" && pwd)" 如果[！ -f“$TOOLKIT_DIR/package.json”];那么 echo“错误：未安装 nextjs-migration-toolkit。” >&2 echo "运行：npx Skills add blazity/next-migration-skills -s nextjs-migration-toolkit" >&2 echo “那就重试这个技能吧。” >&2 1号出口菲 bash“$TOOLKIT_DIR/scripts/setup.sh”>/dev/null ## 版本特定模式在应用任何迁移模式之前，请检查目标 Next.js 版本。读取“.migration/target-version.txt”（如果存在），或询问用户。然后读取对应版本的pattern文件： SKILL_DIR="$(cd "$(目录名"$SKILL_PATH")" && pwd)" 猫“$SKILL_DIR/../version-patterns/nextjs-<版本>.md” **影响数据层迁移的关键版本差异：** * **Next.js 14** ： `cookies()` 和 `headers()` 是同步的 — 不要使用 `await` * **Next.js 15+** ： `cookies()` 和 `headers()` 是异步的 — 必须使用 `await` * **Next.js 14** ：默认情况下会缓存 fetch — 使用 `{ cache: 'no-store' }` 进行 SSR 替换 * **Next.js 15+** ：默认情况下不缓存 fetch — SSR 替换不需要缓存选项下面的示例显示了带有“await”的 Next.js 15+ 模式。如果针对 Next.js 14，请从“cookies()”和“headers()”调用中删除“await”。 ## 步骤 ### 1\.分析数据获取模式 npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" 转换数据获取 npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" 分析路由 ### 2\.迁移 getStaticProps **之前：** 从“下一个”导入{GetStaticProps}；导出 const getStaticProps: GetStaticProps = async () => { const res = wait fetch('https://api.example.com/posts'); const posts =等待res.json(); 返回 { props: { posts }, 重新验证: 60 }; }; 导出默认函数 BlogPage({ posts }) { 返回

{p.title}

; } **之后**（`app/blog/page.tsx`）：导出默认异步函数 BlogPage() { const posts = wait fetch('https://api.example.com/posts', { 下一个：{重新验证：60}， }).then(r => r.json()); 返回

{p.title}

; } 规则： * 组件是“async”——数据获取发生在主体中 * 不重新验证：`{cache: 'force-cache'}`（App Router 中的默认设置） * 重新验证：`{ next: { revalidate: <秒> } }` * 完全删除 getStaticProps 导出 * 无 props 间接 - 获取结果直接进入 JSX ### 3\.迁移 getServerSideProps **之前：** 从“下一个”导入{GetServerSideProps}；导出 const getServerSideProps: GetServerSideProps = async (context) => { const { slug } = context.params; const token = context.req.cookies.token; const res = 等待 fetch(`https://api.example.com/posts/${slug}`, { headers: { 授权: `Bearer ${token}` }, }); const post = 等待 res.json(); 返回 { 道具：{ post } }; }; 导出默认函数 PostPage({ post }) { 返回

{post.title}

{post.content}

; } **之后**（`app/blog/[slug]/page.tsx`）：从'next/headers'导入{cookies}；导出默认异步函数 PostPage({ params }: { params: { slug: string } }) { const cookieStore = 等待 cookies(); const token = cookieStore.get('token')?.value; const post =等待 fetch(`https://api.example.com/posts/${params.slug}`, { 缓存：'无存储'， headers: { 授权: `Bearer ${token}` }, }).then(r => r.json()); 返回

{post.title}

{post.content}

; } 规则： * 页面组件上的 `context.params` → `params` 属性 * `context.query` → `searchParams` 属性 * `context.req.cookies` → `cookies()` 来自 `next/headers` * `context.req.headers` → `headers()` 来自 `next/headers` * 始终使用 `{ cache: 'no-store' }` 来匹配 getServerSideProps 行为 ### 4\.迁移 getStaticPaths **之前：** 从 'next' 导入 { GetStaticPaths, GetStaticProps }; 导出 const getStaticPaths: GetStaticPaths = async () => { const res = wait fetch('https://api.example.com/posts'); const posts =等待res.json(); 返回{ 路径： posts.map((p) => ({ params: { slug: p.slug } })), 后备：'阻塞'， }; }; 导出 const getStaticProps: GetStaticProps = async ({ params }) => { const post = wait fetch(`https://api.example.com/posts/${params.slug}`).then(r => r.json()); 返回 { 道具：{ post } }; }; **之后**（`app/blog/[slug]/page.tsx`）：导出异步函数generateStaticParams() { const posts = wait fetch('https://api.example.com/posts').then(r => r.json()); 返回 posts.map((p) => ({ slug: p.slug })); } 导出默认异步函数 PostPage({ params }: { params: { slug: string } }) { const post = wait fetch(`https://api.example.com/posts/${params.slug}`).then(r => r.json()); 返回

{post.title}

; } 规则： * 返回平面参数对象（不包含在 `{ params: {} }` 中） * `fallback: 'blocking'` / `fallback: true` → 由 App Router 自动处理（为加载 UI 添加 `loading.tsx`） * `fallback: false` → 未转换的路径默认为 404 ### 5\.迁移 API 路由 **之前** (`pages/api/posts.ts`)：从 'next' 导入类型 { NextApiRequest, NextApiResponse }; 导出默认异步函数处理程序（req：NextApiRequest，res：NextApiResponse）{ if (req.method === 'POST') { const { 标题，内容 } = req.body; const post = wait db.posts.create({ 标题, 内容 }); 返回 res.status(201).json(post); } const posts =等待db.posts.findMany(); 返回 res.status(200).json(posts); } **之后**（`app/api/posts/route.ts`）：从 'next/server' 导入 { NextRequest, NextResponse }; 导出异步函数 GET() { const posts =等待db.posts.findMany(); 返回 NextResponse.json(posts); } 导出异步函数 POST(request: NextRequest) { const { 标题，内容 } = wait request.json(); const post = wait db.posts.create({ 标题, 内容 }); 返回 NextResponse.json(post, { status: 201 }); } 规则： * 每个路由一个文件，名为“route.ts”（不是处理程序名称） * 每个 HTTP 方法单独命名导出（GET、POST、PUT、DELETE、PATCH） * `req.body` → `await request.json()` * `res.status(N).json(data)` → `NextResponse.json(data, { status: N })` * `res.redirect(url)` → `NextResponse.redirect(new URL(url, request.url))` ### 6\.验证数据层 npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" 验证验证 app/ 目录中没有保留旧的数据获取模式。 ## 常见陷阱 ### 在 getServerSideProps 替换中忘记 `{ cache: 'no-store' }` **症状**：页面显示陈旧数据或行为类似于静态页面。 **原因**：App Router 默认为“{cache: 'force-cache' }”。如果没有“{cache: 'no-store'}”，获取结果将在构建时缓存——与 getServerSideProps 行为相反。 **修复**：替换 getServerSideProps 时始终添加 `{ cache: 'no-store' }`。 ### 在路由处理程序中使用 `req` / `res` 对象 **错误**：“req 未定义”或 NextApiRequest 上出现类型错误。 **原因**：App Router 路由处理程序使用“NextRequest”（基于 Web API），而不是“NextApiRequest”（基于 Node.js）。 **修复** ：替换 `req.body` → `await request.json()`、`req.query` → `request.nextUrl.searchParams`、`res.json()` → `NextResponse.json()`。 ### 异步 cookies() 和 headers() **错误**：`cookies()` 或 `headers()` 返回 Promise，而不是直接返回值。 **原因**：在 Next.js 15+ 中，`cookies()` 和 `headers()` 是异步的。在 Next.js 13-14 中，它们是同步的。 **修复**：使用 `const cookieStore = wait cookies()`，然后使用 `cookieStore.get('name')`。 ### 混合 getStaticProps 和 getServerSideProps 模式 **错误**：将“{cache: 'force-cache'}”与每次请求时都会更改的动态数据一起使用。 **右**：将缓存策略与原始行为相匹配： * getStaticProps（不重新验证）→ `{ cache: 'force-cache' }` 或省略（默认） * getStaticProps（带重新验证）→ `{ next: { revalidate: N } }` * getServerSideProps → `{ 缓存：'无存储' }` ### 路由处理程序返回错误类型 **错误**：路由处理程序必须返回“Response”对象。 **修复**：始终返回 `NextResponse.json(data)`、`NextResponse.redirect()` 或 `new Response(body)`。不要返回普通对象。 ### 将服务器数据获取转换为客户端 useEffect + fetch **错误**：页面具有获取数据的“getServerSideProps”。您创建页面“use client”并将数据获取替换为“useEffect”： // 错误——数据只有在客户端执行 JS 后才会出现 '使用客户端'；从 'react' 导入 { useState, useEffect }; 导出默认函数 Page() { const [数据，setData] = useState(null); 使用效果（（）=> { fetch('/api/data').then(r => r.json()).then(setData); }, []); if (!data) return

正在加载...

; 返回

{data.value}

; } **右**：将数据获取保留在异步服务器组件中。仅将交互式 UI 提取到客户端组件中。 // app/page.tsx（服务器组件）导出默认异步函数 Page() { const data = wait fetch('https://api.example.com/data', { cache: 'no-store' }).then(r => r.json()); 返回

{data.value}

; } **规则** ：切勿在客户端组件中将 `getServerSideProps` 或 `getStaticProps` 替换为 `useEffect` \+ `fetch`。数据获取必须保留在异步服务器组件的服务器端。添加“使用客户端”的唯一原因是为了交互式 UI（钩子、事件处理程序），并且该组件接收已获取的数据作为 props。

数据层迁移

包含技能