Next.js App Router vs Pages Router 深度实战与迁移白皮书

在 Next.js 13+ 的生态中，App Router 和 Pages Router 是两条截然不同的技术路线。本文基于 2025 年 8 月的实战经验，深入对比两者的架构差异、数据获取方式、布局系统及性能特性，并提供从 Pages Router 迁移到 App Router 的完整指南。无论你是正在评估新项目技术选型，还是计划重构现有应用，这份白皮书都将为你提供硬核的决策依据。

适用场景与技术亮点

本文档主要面向 Next.js 开发者，用于在项目初期或重构时，对比 App Router 和 Pages Router 的架构差异、数据获取方式、布局系统、以及性能特性，从而做出技术选型决策。最适合的团队是那些正在从 Pages Router 迁移到 App Router，或者在新项目中评估是否采用 App Router 的团队。

核心亮点：

• App Router：基于 React Server Components，支持流式渲染、嵌套布局、并行路由和拦截路由，适合需要高性能和复杂交互的现代应用。
• Pages Router：基于文件系统路由，API 简单直观，生态成熟，适合中小型项目或快速原型开发。
• 共存模式：Next.js 13+ 支持在同一个项目中同时使用两者，允许渐进式迁移。

架构优势与同类方案对比

独特卖点：App Router 的嵌套布局和流式渲染是 Pages Router 无法直接实现的。例如，在 App Router 中，你可以通过 layout.js 定义共享的导航栏和页脚，而 page.js 只负责内容区域，实现真正的组件级复用。

安装与核心启动命令

Next.js 项目创建命令（基于 create-next-app）：

bash
# 创建新项目（默认使用 App Router）
npx create-next-app@latest my-app

# 创建项目时选择 Pages Router
npx create-next-app@latest my-app --use-pages-router

# 在现有项目中启用 App Router（手动创建 app/ 目录）
mkdir app

注意：App Router 和 Pages Router 可以共存，但需确保 app/ 和 pages/ 目录下的路由不冲突。

启动参数对照表格

Claude Desktop 与 Cursor 集成配置

虽然本文档不涉及 MCP 服务，但为了演示如何将 Next.js 路由对比知识集成到 AI 工具中，以下是一个假设的 MCP 服务器配置示例：

json
{
  "mcpServers": {
    "nextjs-router-comparison": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-nextjs-router-comparison",
        "--source",
        "https://dev.to/shyam0118/app-router-vs-pages-router-in-nextjs-a-deep-practical-guide-341g"
      ]
    }
  }
}

集成步骤：

1. 在 Claude Desktop 或 Cursor 中打开设置。
2. 找到 MCP 服务器配置部分。
3. 将上述 JSON 粘贴到 claude_desktop_config.json 或 Cursor 的 settings.json 中。
4. 重启应用，即可在对话中查询 App Router 和 Pages Router 的对比信息。

注意：此 MCP 服务器为假设示例，实际使用时需替换为真实可用的包名。

生产环境部署建议与安全限制

安全限制

• 路由访问控制：App Router 和 Pages Router 均不支持基于角色的路由访问控制。建议在中间件或 API 路由中实现认证逻辑。
• CSRF 防护：对于 API 路由，建议使用 csrf 库或 next-auth 等认证方案。
• XSS 防护：在客户端组件中渲染用户输入时，务必使用 dangerouslySetInnerHTML 的替代方案（如 DOMPurify）。

并发表现

• App Router：流式渲染在并发请求下表现优异，但需注意 Server Components 的缓存策略。
• Pages Router：静态生成（SSG）在并发下性能稳定，但动态渲染（SSR）可能成为瓶颈。

磁盘读写优化

• 缓存策略：使用 next.config.js 中的 experimental.staleTimes 控制缓存过期时间。
• 静态资源：将图片、字体等静态资源托管到 CDN，减少服务器磁盘 I/O。

常见报错与故障排除

错误 1：App Router 中无法使用 getServerSideProps

错误信息：Error: getServerSideProps is not supported in app/ 解决方案：在 App Router 中，数据获取应使用 Server Components 中的 async/await 直接 fetch，或使用 generateStaticParams 进行静态生成。不再支持 Pages Router 的 getServerSideProps 和 getStaticProps。

javascript
// App Router 中的数据获取
export default async function Page() {
  const data = await fetch('https://api.example.com/data');
  const json = await data.json();
  return <div>{json.title}</div>;
}

错误 2：App Router 中 layout.js 和 page.js 命名冲突

错误信息：Error: Both layout.js and page.js found in same directory 解决方案：确保 layout.js 和 page.js 位于同一目录下，且 layout.js 用于定义共享布局，page.js 用于定义页面内容。不要在同一目录下同时使用 index.js 和 page.js。

bash
# 正确的目录结构
app/
  layout.js   # 共享布局
  page.js     # 首页内容
  about/
    page.js   # 关于页面

错误 3：App Router 中客户端组件无法使用 async/await

错误信息：Error: async/await is not supported in Client Components 解决方案：客户端组件（'use client'）不支持 async/await 直接获取数据。应使用 useEffect 和 useState，或使用 SWR/React Query 等库。Server Components 才支持 async/await。

javascript
// 客户端组件中的数据获取
'use client';
import { useEffect, useState } from 'react';

export default function ClientPage() {
  const [data, setData] = useState(null);
  useEffect(() => {
    fetch('https://api.example.com/data')
      .then(res => res.json())
      .then(setData);
  }, []);
  return <div>{data?.title}</div>;
}

错误 4：App Router 中中间件无法访问请求体

错误信息：Error: Request body is not available in middleware 解决方案：Next.js 中间件基于 Edge Runtime，不支持读取请求体。如果需要基于请求体内容进行路由重定向，应在 API 路由或 Server Actions 中处理。

javascript
// 在 API 路由中处理请求体
export async function POST(request) {
  const body = await request.json();
  if (body.redirect) {
    return new Response(null, { status: 302, headers: { Location: '/new-path' } });
  }
  return new Response('OK');
}

常见问题解答 (FAQ)

Q: App Router 和 Pages Router 可以共存吗？

A: 可以。Next.js 13+ 支持在同一个项目中同时使用 App Router 和 Pages Router。App Router 的页面位于 app/ 目录，Pages Router 的页面位于 pages/ 目录。两者可以互相链接，但需要注意数据获取方式和布局系统的差异。例如，你可以在 pages/ 中使用 getServerSideProps，同时在 app/ 中使用 Server Components。

Q: App Router 是否完全替代了 Pages Router？

A: 目前没有。Next.js 官方表示 Pages Router 将继续得到支持，但新功能（如 Server Components、流式渲染）将优先在 App Router 中实现。对于新项目，官方推荐使用 App Router；对于现有项目，可以逐步迁移。预计在 Next.js 15+ 中，Pages Router 将进入维护模式，但不会立即移除。

Q: App Router 对 SEO 有影响吗？

A: App Router 默认支持服务器端渲染（SSR）和静态生成（SSG），对 SEO 友好。但需要注意，客户端组件中的内容可能不会被搜索引擎爬取。建议将关键 SEO 内容（如标题、描述、结构化数据）放在 Server Components 中。此外，App Router 的流式渲染可能导致搜索引擎爬虫在页面完全加载前抓取，建议使用 loading.js 或 Suspense 边界控制内容呈现顺序。

Q: 从 Pages Router 迁移到 App Router 的最佳策略是什么？

A: 推荐渐进式迁移策略：

1. 在现有项目中创建 app/ 目录。
2. 将共享布局（如导航栏、页脚）迁移到 app/layout.js。
3. 逐个将页面从 pages/ 迁移到 app/，优先迁移静态页面。
4. 对于需要 getServerSideProps 的页面，使用 Server Components 替代。
5. 测试并验证每个页面的功能，确保无回归。
6. 最终移除 pages/ 目录（可选）。

相关深度解决方案

• 在配置当前服务时，如果您需要实现更复杂的架构或多源数据整合，建议配合参考我们整理的 Next.js ISR On-Demand Revalidation 深度实战与 Cursor 集成白皮书。
• 在配置当前服务时，如果您需要实现更复杂的架构或多源数据整合，建议配合参考我们整理的 Redis Caching 集成 Node.js 深度实战与 Cursor 集成白皮书。