从 Pages Router 迁移到 Next.js App Router 的注意事项

从 Pages Router 迁移到 App Router，本质上不是一次简单的目录结构重命名，而是从“基于单页面的客户端整树水合（Hydration）”向“基于 React Server Components (RSC) 与嵌套流式渲染”的心智模型升级。Next.js 原生支持两个路由器在同一个项目中完全共存，因此最具确定性且风险最低的实施路径是渐进式增量迁移（Incremental Adoption），无需停机或推倒重写。本文针对迁移过程中的路由共存、根布局重构、数据获取范式转变、组件边界划分及上线前验证清单，提供全面且具体的技术实操指引。

一、渐进式共存机制与目录治理策略

面对已有的大型线上系统，许多开发者直觉认为迁移需要“全量切换”，甚至新建一个独立仓库重新实现全部功能。这种做法不仅会拉长研发周期，还会将业务暴露在巨大的回归风险之中。实际上，Next.js 设计之初就将 pages/ 与 app/ 目录的共存作为一等公民能力予以支持。

在同一个代码仓库内，你可以同时保留 pages/ 与 app/ 两个顶层目录。Next.js 内部的路由分发中心会在启动和打包时统一扫描这两个目录，为不同的请求路径匹配对应的处理器。这使得团队可以按页面、甚至按接口逐步推进改造。

1. 路由优先级与碰撞避让

当开发者不小心在两个目录中定义了完全相同的路由路径时（例如既存在 pages/about.tsx，又建立了 app/about/page.tsx），Next.js 的默认决策规则是：App Router 的优先级高于 Pages Router，来自 /about 的访问请求将直接交由 app/about/page.tsx 响应，而 pages/about.tsx 则会被静默忽略。

2. 推荐的渐进式迁移顺序

迁移切忌从最复杂的核心交易链路开始。建议按照以下由浅入深的四阶节奏推进：

1. 新增页面直接入驻：项目中所有全新的业务需求和新路由，一律强制在 app/ 目录下新建，团队在实践中熟悉 RSC 与 Metadata 规范。
2. 独立无依赖叶子页：挑选业务逻辑简单、无重度状态依赖的静态页面进行试水，如“关于我们”、“服务协议”、“404 错误页”等。
3. 动态内容展示页：迁移文章详情页（/blog/[id]）、产品介绍页等，重点攻克 getServerSideProps 转换为异步 Server Component 的数据拉取逻辑。
4. 复杂中枢与全局上下文页：最后迁移依赖全局用户登录态（Auth Context）、复杂购物车状态、表单交互重度绑定的用户中心和结算链路。

二、根脚手架重构：从 _app / _document 到 Root Layout

在 Pages Router 中，所有页面的生命周期和全局外壳由 pages/_app.tsx 和 pages/_document.tsx 共同承载。但在 App Router 中，这两个特殊文件对 app/ 下的任何子路由均完全失效。

取而代之的是位于 app/layout.tsx 的根布局（Root Layout）。根布局具有不可替代的强制约束规则：

• 必须声明 HTML 与 Body 标签：app/layout.tsx 必须显式返回 <html> 和 <body> 标签。而在子目录布局（如 app/dashboard/layout.tsx）中，绝对不能再次包含这两个标签。
• 全局 CSS 的唯一宿主：原先在 _app.tsx 中引入的全局样式文件（如 import '../styles/globals.css'），现在必须直接在 app/layout.tsx 中引入。
• 天然服务端组件：app/layout.tsx 默认是一个 React Server Component，绝不能在该文件顶层添加 'use client'。

1. 全局 Context Provider 的迁移陷阱

在 pages/_app.tsx 中，我们通常会包裹各种全局 Provider，例如 Redux、React Query、主题 ThemeProvider 以及鉴权 AuthProvider：

// 旧版 pages/_app.tsx 中的常见写法
export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <ThemeProvider>
      <AuthProvider>
        <Component {...pageProps} />
      </AuthProvider>
    </ThemeProvider>
  );
}

由于 React Context API 依赖客户端运行时，直接将这些 Provider 放在默认作为服务端组件的 app/layout.tsx 中，会导致 createContext is not a function 或服务端执行报错。

正确解法：将所有客户端 Provider 抽取聚合到一个独立的客户端包装组件中，然后在根布局中以嵌套子节点形式引入：

// 步骤 1：新建 app/providers.tsx，顶部显式标记 'use client'
'use client';

import React from 'react';
import { ThemeProvider } from '@/context/theme';
import { AuthProvider } from '@/context/auth';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider>
      <AuthProvider>{children}</AuthProvider>
    </ThemeProvider>
  );
}

// 步骤 2：在 app/layout.tsx 中引入，保持根布局仍为 Server Component
import './globals.css';
import { Providers } from './providers';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="zh-CN">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

2. 废弃 next/head，全面接入 Metadata API

在 Pages Router 中，页面通过 import Head from 'next/head' 并在 JSX 中渲染 <Head><title>...</title></Head> 来管理 SEO 标签。

在 App Router 中，严禁在 app/ 内使用 next/head。Next.js 提供了更加标准化且类型安全的内置 Metadata API：

• 静态元数据：直接在 layout.tsx 或 page.tsx 中导出 metadata 常量对象：

  import type { Metadata } from 'next';
  
  export const metadata: Metadata = {
    title: '用户工作台 - 运营管理平台',
    description: '提供实时数据看板与业务分析报表',
  };

• 动态元数据：当页面标题依赖接口数据时，导出 generateMetadata 异步函数：

  export async function generateMetadata({ params }: { params: Promise<{ id: string }> }): Promise {
    const { id } = await params;
    const item = await fetchItem(id);
    return {
      title: `${item.name} - 详情页`,
      description: item.summary,
    };
  }

三、数据获取范式重构：告别 getServerSideProps 与 getStaticProps

Pages Router 的核心数据契约是页面顶层导出的生命周期函数：getServerSideProps（动态 SSR）、getStaticProps（静态生成 SSG）以及 getInitialProps。在 App Router 中，这三大函数全部被废弃，页面中导出它们不会产生任何效果。

1. 从外置生命周期到异步组件直接获取

由于 App Router 下的所有页面和组件默认都是 React Server Components，组件函数本身就支持声明为 async。数据获取逻辑不再需要在外层函数打好包再作为 props 一层层向内传递，而可以直接在组件内部就地调用：

// app/blog/[id]/page.tsx
interface PageProps {
  params: Promise<{ id: string }>;
}

export default async function BlogPostPage({ params }: PageProps) {
  const { id } = await params;
  
  // 直接在服务端组件内部调用数据请求
  const res = await fetch(`https://api.example.com/posts/${id}`, {
    // 控制缓存策略（下文重点讲解）
    next: { revalidate: 3600 }
  });
  
  if (!res.ok) {
    throw new Error('无法加载文章数据');
  }
  
  const post = await res.json();

  return (
    <article>
      <h1>{post.title}</h1>
      <div>{post.content}</div>
    </article>
  );
}

2. 关键辨析：为什么我的数据修改后页面不刷新？（缓存机制巨变）

这是从 Pages Router 迁移过来的开发者遇到频率最高的“困惑”。

在 Pages Router 中，只要写了 getServerSideProps，每一次来自浏览器的访问都会在 Node 服务端重新执行该函数，因此数据永远是“实时”的。

但在 App Router 中，Next.js 在全局架构上内置了四层缓存，尤其扩展了原生 fetch，引入了 Data Cache。如果直接使用未经配置的 fetch(url)，Next.js 会将其视为持久缓存（在生产环境中默认缓存直至显式失效）。即使页面是动态路由，数据也可能被固化。

业务诉求	Pages Router 旧实现	App Router 正确对应写法
纯静态构建 (SSG)	getStaticProps	默认 fetch(url) 或 fetch(url, { cache: 'force-cache' })
定时重验证 (ISR)	getStaticProps + revalidate	fetch(url, { next: { revalidate: 60 } })
每次请求必最新 (SSR)	getServerSideProps	fetch(url, { cache: 'no-store' }) 或在路由顶部导出 export const dynamic = 'force-dynamic'

四、组件心智模型转换：客户端与服务端组件边界划分

在 Pages Router 中，几乎所有写在组件文件里的代码都会被编译并打包进客户端 JS 中。而在 App Router 中，React 划分了两种组件类型：

• React Server Component (RSC)：无需向浏览器传输任何 JS 代码，拥有零客户端打包体积（Zero-bundle-size），天然安全地访问数据库与私密环境变量。
• Client Component：通过文件第一行的 'use client'; 指令进行标记，拥有完整的浏览器事件与 React 状态。

1. 核心误区：'use client' 不等于仅在浏览器运行

许多开发者望文生义，误以为一旦写了 'use client'，该组件就变成了单页应用（SPA）并在浏览器端白屏渲染。

真相：声明了 'use client' 的组件在首次用户请求时，依然会在 Node.js 服务端进行一次完整的服务端预渲染（SSR）并生成初始 HTML 字符串，随后才在浏览器端进行事件水合。因此，如果你在 Client Component 的顶层函数体中直接写 const token = localStorage.getItem('token') 或直接访问 window.innerWidth，依然会报出 ReferenceError: window is not defined 的经典错误。

所有依赖浏览器专属全局变量的操作，必须严格限制在 useEffect 钩子内，或在确保组件已挂载（Mounted）之后执行。

2. 组件树组合黄金法则：以 children 注入服务端插槽

迁移时经常会遇到一个结构性难题：父组件需要响应点击收起等客户端交互（必须是 Client Component），但它包裹的内容区域非常庞大，且内部包含耗时的数据拉取（最适合作为 Server Component）。

错误反例：在 Client Component 内部直接 import ServerList from './ServerList'。这样会导致 ServerList 被强制转变为客户端组件，其所有依赖和逻辑都会被打包进客户端 JS 中。

正确解法（依赖注入 / 插槽模式）：利用 React 的 children 属性作为中立通道，在更外层的服务端组件中完成组装：

// 1. components/Accordion.tsx (客户端组件，专注处理折叠状态)
'use client';

import { useState } from 'react';

export default function Accordion({ children }: { children: React.ReactNode }) {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <div className="accordion-box">
      <button onClick={() => setIsOpen(!isOpen)}>
        {isOpen ? '折叠内容' : '展开详情'}
      </button>
      {isOpen && <div className="content">{children}</div>}
    </div>
  );
}

// 2. app/page.tsx (服务端页面组件，在此负责连接组合)
import Accordion from '@/components/Accordion';
import HeavyServerData from '@/components/HeavyServerData'; // 依然是服务端组件

export default function HomePage() {
  return (
    <main>
      <h1>业务控制台</h1>
      {/* HeavyServerData 在服务端执行拉取，渲染出的结构无缝注入 Accordion 的 children */}
      <Accordion>
        <HeavyServerData />
      </Accordion>
    </main>
  );
}

五、API 路由与路由钩子（Hooks）的全面升级

1. 从 pages/api 到 Route Handlers

在 Pages Router 中，接口文件存放在 pages/api/ 目录下，导出形式为一个接收 Node 原生 req 和 res 的处理函数。而在 App Router 中，接口文件必须命名为 app/api/.../route.ts（被称为 Route Handler），且底层遵循标准 Web Fetch API：

// Pages Router 旧写法：pages/api/user.ts
import type { NextApiRequest, NextApiResponse } from 'next';

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === 'POST') {
    const body = req.body;
    return res.status(200).json({ status: 'ok', data: body });
  }
  return res.status(405).end();
}

// App Router 现代写法：app/api/user/route.ts
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const body = await request.json();
  return NextResponse.json({ status: 'ok', data: body }, { status: 200 });
}

2. 路由钩子重构：next/router 与 next/navigation 的划分

在 Pages Router 中，所有路由状态（路径、参数、跳转方法）均由 import { useRouter } from 'next/router' 统一提供。

在 App Router 中，如果在一个组件中尝试从 next/router 导入 useRouter，应用会直接抛出运行错误：NextRouter was not mounted。正确的做法是全面转向 next/navigation：

• 页面跳转：import { useRouter } from 'next/navigation'，提供 router.push()、router.replace()、router.refresh()。
• 当前路径：从 useRouter().pathname 改为调用 import { usePathname } from 'next/navigation'。
• 查询参数：从 useRouter().query 改为调用 import { useSearchParams } from 'next/navigation'。
• 服务端重定向：在 Server Component 或 Server Actions 中，直接调用 import { redirect } from 'next/navigation'。

六、全流程迁移落地四步法与上线核查清单

为了让迁移过程具备明确的验收节点与排错指引，推荐遵循结构化的“四阶段闭环路径”，并在正式切流上线前依照清单逐项核对。

上线前四大关键核查项（Checklist）

1. 缓存策略是否符合业务预期： 仔细审查重构后的页面与接口。对于需要实时反映登录状态或后台最新变更的数据，确认是否配置了 cache: 'no-store' 或 dynamic = 'force-dynamic'，严防页面因强缓存变成陈旧数据。
2. 路由钩子与导入清理： 在工程根目录下执行全文正则搜索 from ['"]next/router['"]，确保 app/ 目录下的代码中零残留。检查所有动态路由组件对 params 的获取方式。
3. 全局 Provider 穿透性测试： 切换不同路由时，验证深层组件是否能够稳定获取 Theme、Redux 或国际化上下文。重点核验在从旧的 Pages 页面通过 <Link> 跳转到新的 App 页面时，全局状态是否会重置。
4. SEO 与 SSR 源码核验： 在浏览器中直接右键点击“查看网页源代码”（View Page Source），确认页面在服务端输出的原始 HTML 中是否已包含正确的 <title>、<meta name="description"> 以及核心正文内容，杜绝客户端水合覆盖导致的 SEO 降权。

七、高频排错速查与典型场景答疑

Q1：Next.js 15+ 中 params 报类型不匹配或 undefined？

解答：在 Next.js 15 及更高版本中，为了实现更彻底的异步请求并发优化，页面组件的 params 和 searchParams 从原先的同步对象转变为 Promise。在组件中必须显式 await 之后才能访问内部属性：

// Next.js 15+ 兼容规范写法
export default async function Page({
  params,
  searchParams,
}: {
  params: Promise<{ slug: string }>;
  searchParams: Promise<{ [key: string]: string | undefined }>;
}) {
  const { slug } = await params;
  const query = await searchParams;
  return <div>当前栏目：{slug}</div>;
}

Q2：老旧第三方 UI 组件库不支持 RSC 报错怎么办？

解答：部分社区旧组件库尚未在源码顶层标注 'use client'，一旦在 Server Component 中引入，就会报 React.createContext is not a function。此时无需等待库作者更新，只需在本地项目中建立一个适配包装文件：

// components/wrapped-chart.tsx
'use client';

// 在声明了 'use client' 的文件中重新导出第三方组件
export { LegacyChartComponent as Chart } from 'some-legacy-chart-lib';

随后在服务端页面中改为引入这个本地包装文件即可安全运行。