引言：Next.js 13 的范式转变
Next.js 13 引入了 App Router（应用路由）作为新的默认路由机制，这是一个颠覆性的变化，它彻底改变了我们构建 React 应用的方式。与传统的 Pages Router（基于文件系统的页面路由）相比，App Router 基于 React Server Components (RSC) 构建，提供了更强大的服务器端渲染能力、更细粒度的数据获取和更优化的性能表现。
对于现有的 Pages Router 项目，迁移到 App Router 不是一个简单的文件重命名过程，而是一个需要理解新概念、重构组件和调整数据流的系统性工程。本指南将带你从零开始，深入理解 App Router 的核心概念，提供详细的迁移步骤，并针对迁移过程中的常见难题给出解决方案。
1. 理解 App Router 的核心概念
在开始迁移之前，我们必须先理解 App Router 与 Pages Router 的根本区别。
1.1 目录结构的变化
Pages Router (传统模式):
pages/
index.js # 首页
about.js # 关于页面
posts/
[id].js # 动态路由：/posts/123
index.js # /posts
App Router (新模式):
app/
layout.tsx # 根布局
page.tsx # 首页
about/
page.tsx # 关于页面
posts/
[id]/
page.tsx # 动态路由：/posts/123
layout.tsx # posts 分组的布局
page.tsx # /posts
关键变化：
layout.tsx
: 定义共享 UI，支持嵌套
page.tsx
: 定义页面内容
路由段
: 每个文件夹都是一个路由段
文件扩展名
: 推荐使用
.tsx
/
.ts
（TypeScript）
1.2 React Server Components (RSC) vs Client Components
这是 App Router 最核心的概念。默认情况下，所有组件都是
Server Components
，它们：
在服务器上渲染，不打包到客户端 JavaScript
可以直接访问后端资源（文件系统、数据库、API）
没有 React Hooks（useState, useEffect 等）
不能使用浏览器 API
Client Components
需要显式声明：
// app/some-component.tsx
‘use client’; // 必须在文件顶部

import { useState } from ‘react’;

export default function SomeComponent() {
const [count, setCount] = useState(0);
return ;
}
1.3 数据获取方式的改变
Pages Router:
// pages/posts/[id].tsx
export async function getServerSideProps(context) {
const res = await fetch(`https://api.example.com/posts/${context.params.id}`);
const post = await res.json();
return { props: { post } };
}

export default function Post({ post }) {
return

{post.title}

;
}
App Router:
// app/posts/[id]/page.tsx
async function getPost(id: string) {
const res = await fetch(`https://api.example.com/posts/${id}`, {
cache: ‘no-store’ // 或者 ‘force-cache’
});
return res.json();
}

export default async function PostPage({ params }: { params: { id: string } }) {
const post = await getPost(params.id);
return

{post.title}

;
}
2. 迁移前的准备工作
2.1 环境升级
首先确保你的开发环境满足要求：
# 升级 Next.js 到 13+
npm install next@latest react@latest react-dom@latest

# 如果使用 TypeScript，确保类型定义
npm install -D @types/react @types/react-dom

# 安装 ESLint 插件（可选但推荐）
npm install -D eslint-config-next
2.2 配置文件更新
next.config.js:
/** @type {import(‘next’).NextConfig} */
const nextConfig = {
// 如果你暂时不想使用 App Router，可以显式禁用
// experimental: {
// appDir: false,
// },

// 推荐启用 TypeScript 和 ESLint
typescript: {
ignoreBuildErrors: false,
},
eslint: {
ignoreDuringBuildErrors: false,
},
};

module.exports = nextConfig;
tsconfig.json:
{
“compilerOptions”: {
“target”: “ES2017”,
“lib”: [“dom”, “dom.iterable”, “esnext”],
“allowJs”: true,
“skipLibCheck”: true,
“strict”: true,
“noEmit”: true,
“esModuleInterop”: true,
“module”: “esnext”,
“moduleResolution”: “bundler”,
“resolveJsonModule”: true,
“isolatedModules”: true,
“jsx”: “preserve”,
“incremental”: true,
“plugins”: [
{
“name”: “next”
}
],
“baseUrl”: “.”,
“paths”: {
“@/*”: [“./*”]
}
},
“include”: [“next-env.d.ts”, “**/*.ts”, “**/*.tsx”, “.next/types/**/*.ts”],
“exclude”: [“node_modules”]
}
2.3 规划迁移策略
对于大型项目，建议采用
渐进式迁移
策略：
并行运行
: 保持现有 Pages Router，同时在
app/
目录下创建新页面
逐步迁移
: 从叶子页面开始，逐步向上迁移
共享组件
: 识别可复用的组件，优先转换为 Client Components
测试覆盖
: 确保每个迁移的页面都有充分的测试
3. 核心迁移步骤详解
3.1 创建基础 App 结构
首先创建 App Router 的基础骨架：
app/
layout.tsx # 根布局
page.tsx # 首页
error.tsx # 错误边界
loading.tsx # 加载状态
not-found.tsx # 404 页面
global.css # 全局样式
app/layout.tsx:
import ‘./global.css’;

export const metadata = {
title: ‘My App’,
description: ‘Generated by Next.js’,
};

export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (

{children}

);
}
app/page.tsx:
export default function HomePage() {
return (

Welcome to the new App Router

This is the new home page using App Router

);
}
3.2 迁移动态路由
假设我们有一个 Posts 系统，包含列表页和详情页。
Pages Router:
pages/
posts/
index.tsx # /posts
[id].tsx # /posts/123
App Router:
app/
posts/
layout.tsx # Posts 共享布局
page.tsx # /posts
[id]/
page.tsx # /posts/123
app/posts/page.tsx (列表页):
// 这是一个 Server Component，可以直接获取数据
async function getPosts() {
const res = await fetch(‘https://jsonplaceholder.typicode.com/posts’, {
next: { revalidate: 60 }, // ISR: 60秒重新验证
});
return res.json();
}

export default async function PostsPage() {
const posts = await getPosts();

return (

All Posts

{post.title}

))}

);
}
app/posts/[id]/page.tsx (详情页):
// 动态路由参数通过 params 传入
export default async function PostPage({
params
}: {
params: { id: string }
}) {
const res = await fetch(
`https://jsonplaceholder.typicode.com/posts/${params.id}`
);
const post = await res.json();

return (

{post.title}

{post.body}

← Back to posts

);
}

// 可选：生成静态参数（SSG）
export async function generateStaticParams() {
const posts = await fetch(‘https://jsonplaceholder.typicode.com/posts’).then(
(res) => res.json()
);

return posts.map((post: any) => ({
id: post.id.toString(),
}));
}
3.3 处理 API 路由
Pages Router:
pages/
api/
posts.ts
App Router:
app/
api/
posts/
route.ts
app/api/posts/route.ts:
import { NextResponse } from ‘next/server’;

export async function GET() {
// 处理 GET 请求
const posts = await fetch(‘https://jsonplaceholder.typicode.com/posts’).then(
(res) => res.json()
);
return NextResponse.json(posts);
}

export async function POST(request: Request) {
// 处理 POST 请求
const body = await request.json();
// 保存到数据库…
return NextResponse.json({ message: ‘Post created’, data: body });
}
3.4 处理静态资源
Pages Router:
public/
images/
logo.png
App Router:
app/
favicon.ico
icon.png
opengraph-image.png
twitter-image.png
public/
images/
logo.png
App Router 支持自动元数据图像：
icon.png
– 应用图标
opengraph-image.png
– 社交分享图
twitter-image.png
– Twitter 分享图
4. 解决常见迁移难题
4.1 难题一：客户端组件与服务器组件的边界
问题
: 原有的 Pages Router 组件可能混合了服务器端和客户端逻辑，直接迁移会导致错误。
解决方案
: 明确组件边界，使用
‘use client’
指令。
示例：一个复杂的表单组件
Pages Router (旧):
// pages/contact.tsx
import { useState } from ‘react’;
import { sendEmail } from ‘../lib/email’;

export default function ContactPage() {
const [name, setName] = useState(”);
const [email, setEmail] = useState(”);
const [message, setMessage] = useState(”);
const [status, setStatus] = useState(‘idle’);

return (

setName(e.target.value)} />
setEmail(e.target.value)} />

setMessage(e.target.value)} /> 
 <button type="submit" disabled={status === 'sending'}> 
 {status === ‘sending’ ? ‘Sending…’ : ‘Send’} 
 </button> 
 </form>
 ); 
} 
App Router (新) – 正确的拆分方式: 
app/contact/page.tsx (Server Component): 
// 这是一个 Server Component，负责渲染页面框架 
import ContactForm from ‘./contact-form’;
export default function ContactPage() { 
 return (
<div>
<h1>Contact Us</h1>
Fill out the form below and we’ll get back to you.
 <ContactForm />
 </div>
 ); 
} 
app/contact/contact-form.tsx (Client Component): 
‘use client’;
import { useState } from ‘react’;
// 注意：这里不能直接导入服务器端的数据库操作 
// 需要通过 API 路由来处理 
export default function ContactForm() { 
 const [name, setName] = useState(”); 
 const [email, setEmail] = useState(”); 
 const [message, setMessage] = useState(”); 
 const [status, setStatus] = useState<'idle' | 'sending' | 'success' | 'error'>(‘idle’);
 const handleSubmit = async (e: React.FormEvent) => { 
 e.preventDefault(); 
 setStatus(‘sending’);
 try { 
 const response = await fetch(‘/api/contact’, { 
 method: ‘POST’, 
 headers: { ‘Content-Type’: ‘application/json’ }, 
 body: JSON.stringify({ name, email, message }), 
 });
 if (response.ok) { 
 setStatus(‘success’); 
 // 重置表单 
 setName(”); 
 setEmail(”); 
 setMessage(”); 
 } else { 
 setStatus(‘error’); 
 } 
 } catch { 
 setStatus(‘error’); 
 } 
 };
 return (
<form onSubmit={handleSubmit} className="contact-form">
<div>
 <label>Name:</label> 
 <input 
 value={name} 
 onChange={(e) => setName(e.target.value)} 
 required 
 />
 </div>
<div>
 <label>Email:</label> 
 <input 
 type="email"
 value={email} 
 onChange={(e) => setEmail(e.target.value)} 
 required 
 />
 </div>
<div>
 <label>Message:</label> 
 <textarea 
 value={message} 
 onChange={(e) => setMessage(e.target.value)} 
 required 
 />
 </div>
 <button type="submit" disabled={status === 'sending'}> 
 {status === ‘sending’ ? ‘Sending…’ : ‘Send’} 
 </button>
 {status === ‘success’ && 
Message sent successfully!
} 
 {status === ‘error’ && 
Failed to send message. Please try again.
}
 </form>
 ); 
} 
app/api/contact/route.ts: 
import { NextResponse } from ‘next/server’;
export async function POST(request: Request) { 
 try { 
 const { name, email, message } = await request.json();
 // 这里可以执行服务器端逻辑，如保存到数据库 
 // await db.contacts.create({ name, email, message });
 // 或者发送邮件 
 // await sendEmail({ name, email, message });
 return NextResponse.json({ success: true }); 
 } catch (error) { 
 return NextResponse.json( 
 { error: ‘Failed to process request’ }, 
 { status: 500 } 
 ); 
 } 
} 
4.2 难题二：全局状态管理 
问题 
: 在 Pages Router 中，我们经常使用 Context API 或 Redux 等全局状态管理方案。在 App Router 中，由于 Server Components 不能使用 Context，需要重新设计。 
解决方案 
: 将状态管理限制在 Client Components 内，或使用服务器端状态管理方案。 
示例：用户认证状态 
app/providers.tsx (管理全局状态): 
‘use client’;
import { createContext, useContext, useState, useEffect } from ‘react’; 
import type { User } from ‘@/types’;
interface AuthContextType { 
 user: User | null; 
 login: (email: string, password: string) => Promise<void>; 
 logout: () => void; 
 loading: boolean; 
}
const AuthContext = createContext<AuthContextType | undefined>(undefined);
export function AuthProvider({ children }: { children: React.ReactNode }) { 
 const [user, setUser] = useState<User | null>(null); 
 const [loading, setLoading] = useState(true);
 useEffect(() => { 
 // 检查本地存储或 cookie 
 const storedUser = localStorage.getItem(‘user’); 
 if (storedUser) { 
 setUser(JSON.parse(storedUser)); 
 } 
 setLoading(false); 
 }, []);
 const login = async (email: string, password: string) => { 
 const response = await fetch(‘/api/auth/login’, { 
 method: ‘POST’, 
 headers: { ‘Content-Type’: ‘application/json’ }, 
 body: JSON.stringify({ email, password }), 
 });
 if (response.ok) { 
 const userData = await response.json(); 
 setUser(userData); 
 localStorage.setItem(‘user’, JSON.stringify(userData)); 
 } else { 
 throw new Error(‘Login failed’); 
 } 
 };
 const logout = () => { 
 setUser(null); 
 localStorage.removeItem(‘user’); 
 fetch(‘/api/auth/logout’, { method: ‘POST’ }); 
 };
 return ( 
 <AuthContext.Provider value={{ user, login, logout, loading }}> 
 {children} 
 </AuthContext.Provider> 
 ); 
}
export function useAuth() { 
 const context = useContext(AuthContext); 
 if (context === undefined) { 
 throw new Error(‘useAuth must be used within an AuthProvider’); 
 } 
 return context; 
} 
app/layout.tsx (使用 Provider): 
import ‘./global.css’; 
import { AuthProvider } from ‘./providers’;
export const metadata = { 
 title: ‘My App’, 
 description: ‘Generated by Next.js’, 
};
export default function RootLayout({ 
 children, 
}: { 
 children: React.ReactNode; 
}) { 
 return ( 
 <html lang="en"> 
 <body> 
 <AuthProvider>{children}</AuthProvider> 
 </body> 
 </html> 
 ); 
} 
app/dashboard/page.tsx (使用认证状态): 
import { redirect } from ‘next/navigation’; 
import { AuthProvider } from ‘../providers’; 
import DashboardContent from ‘./dashboard-content’;
// 这是一个 Server Component，可以检查认证状态 
export default async function DashboardPage() { 
 // 在实际应用中，这里应该检查服务器端的认证状态 
 // 例如通过 cookies 或 session 
 // const user = await getCurrentUser();
 // if (!user) { 
 // redirect(‘/login’); 
 // }
 return ( 
 <AuthProvider> 
 <DashboardContent /> 
 </AuthProvider> 
 ); 
} 
app/dashboard/dashboard-content.tsx: 
‘use client’;
import { useAuth } from ‘../providers’;
export default function DashboardContent() { 
 const { user, logout } = useAuth();
 if (!user) { 
 return 
<div>Please log in</div>
; 
 }
 return (
<div>
<h1>Welcome, {user.name}</h1>
 <button onClick={logout}>Logout</button>
 </div>
 ); 
} 
4.3 难题三：路由守卫和中间件 
问题 
: 在 Pages Router 中，我们经常使用 
getServerSideProps 
进行路由保护。在 App Router 中，需要新的方式。 
解决方案 
: 使用中间件（Middleware）或在 Server Components 中进行重定向。 
方案一：使用中间件（推荐） 
middleware.ts (项目根目录): 
import { NextResponse } from ‘next/server’; 
import type { NextRequest } from ‘next/server’;
export function middleware(request: NextRequest) { 
 // 检查受保护的路由 
 if (request.nextUrl.pathname.startsWith(‘/dashboard’)) { 
 const token = request.cookies.get(‘auth-token’)?.value;
 if (!token) { 
 // 重定向到登录页 
 return NextResponse.redirect(new URL(‘/login’, request.url)); 
 }
 // 验证 token 
 // const user = await verifyToken(token); 
 // if (!user) { 
 // return NextResponse.redirect(new URL(‘/login’, request.url)); 
 // } 
 }
 return NextResponse.next(); 
}
export const config = { 
 matcher: [‘/dashboard/:path*’, ‘/admin/:path*’], 
}; 
方案二：在 Server Component 中重定向 
app/dashboard/page.tsx: 
import { redirect } from ‘next/navigation’; 
import { cookies } from ‘next/headers’;
export default async function DashboardPage() { 
 const cookieStore = cookies(); 
 const token = cookieStore.get(‘auth-token’)?.value;
 if (!token) { 
 redirect(‘/login’); 
 }
 // 验证 token 
 // const user = await verifyToken(token); 
 // if (!user) { 
 // redirect(‘/login’); 
 // }
 return (
<div>
<h1>Dashboard</h1>
 {/* 仪表板内容 */}
 </div>
 ); 
} 
4.4 难题四：数据获取与缓存策略 
问题 
: Pages Router 使用 
getServerSideProps 
和 
getStaticProps 
，而 App Router 使用 
fetch 
API 和缓存选项。 
解决方案 
: 理解新的缓存策略并正确应用。 
缓存策略详解: 
// app/posts/[id]/page.tsx
// 1. 动态渲染（每次请求都重新获取） 
export default async function PostPage({ params }: { params: { id: string } }) { 
 const res = await fetch(`https://api.example.com/posts/${params.id}`, { 
 cache: ‘no-store’, // 等同于 getServerSideProps 
 }); 
 const post = await res.json(); 
 return 
<div>{post.title}</div>
; 
}
// 2. 静态渲染（构建时生成，可重新验证） 
export default async function PostPage({ params }: { params: { id: string } }) { 
 const res = await fetch(`https://api.example.com/posts/${params.id}`, { 
 next: { revalidate: 60 }, // ISR: 60秒后重新验证 
 }); 
 const post = await res.json(); 
 return 
<div>{post.title}</div>
; 
}
// 3. 完全静态（构建时生成，永不重新验证） 
export default async function PostPage({ params }: { params: { id: string } }) { 
 const res = await fetch(`https://api.example.com/posts/${params.id}`, { 
 next: { revalidate: false }, // 等同于 getStaticProps 
 }); 
 const post = await res.json(); 
 return 
<div>{post.title}</div>
; 
}
// 4. 使用 generateStaticParams 进行 SSG 
export async function generateStaticParams() { 
 const posts = await fetch(‘https://api.example.com/posts’).then((res) => res.json()); 
 return posts.map((post: any) => ({ id: post.id.toString() })); 
} 
4.5 难题五：错误处理和加载状态 
问题 
: 在 Pages Router 中，错误处理通常在组件内部或通过 Error Boundary 处理。App Router 提供了更细粒度的错误处理。 
解决方案 
: 使用 
error.tsx 
和 
loading.tsx 
。 
app/posts/error.tsx (错误边界): 
‘use client’;
import { useEffect } from ‘react’;
export default function ErrorBoundary({ 
 error, 
 reset, 
}: { 
 error: Error & { digest?: string }; 
 reset: () => void; 
}) { 
 useEffect(() => { 
 // 记录错误到日志服务 
 console.error(‘Posts Error:’, error); 
 }, [error]);
 return (
<div>
<h2>Something went wrong!</h2>
{error.message}
 <button onClick={reset}>Try again</button>
 </div>
 ); 
} 
app/posts/loading.tsx (加载状态): 
export default function Loading() { 
 return (
<div>
<h2>Loading Posts…</h2>
<div className="spinner">⏳</div>
</div>
 ); 
} 
app/posts/page.tsx (使用错误和加载): 
import PostsList from ‘./posts-list’;
export default async function PostsPage() { 
 // 这个组件会自动使用同目录下的 loading.tsx 和 error.tsx 
 return <PostsList />; 
} 
app/posts/posts-list.tsx: 
async function getPosts() { 
 const res = await fetch(‘https://jsonplaceholder.typicode.com/posts’); 
 if (!res.ok) throw new Error(‘Failed to fetch posts’); 
 return res.json(); 
}
export default async function PostsList() { 
 const posts = await getPosts();
 return (
<ul>
 {posts.map((post: any) => (
<li key={post.id}>
<h3>{post.title}</h3>
{post.body.substring(0, 100)}…
</li>
 ))}
 </ul>
 ); 
} 
5. 高级迁移技巧 
5.1 渐进式迁移：混合使用 Pages 和 App Router 
Next.js 13+ 支持在同一个应用中同时使用 Pages Router 和 App Router，这为大型项目提供了平滑迁移路径。 
配置 next.config.js: 
const nextConfig = { 
 // 确保两个路由系统可以共存 
 experimental: { 
 appDir: true, // 启用 App Router 
 }, 
};
module.exports = nextConfig; 
目录结构: 
app/ 
 # 新的 App Router 页面 
 dashboard/ 
 page.tsx 
pages/ 
 # 旧的 Pages Router 页面（暂时保留） 
 legacy/ 
 index.tsx 
在 App Router 中引用 Pages Router 页面: 
// app/legacy-wrapper/page.tsx 
import LegacyPage from ‘../../pages/legacy/index’;
export default function LegacyWrapper() { 
 // 注意：这种方式可能有限制，推荐逐步迁移 
 return <LegacyPage />; 
} 
5.2 处理表单提交和 Action 
App Router 引入了 Server Actions 的概念，允许在表单中直接调用服务器函数。 
app/actions.ts: 
‘use server’;
import { redirect } from ‘next/navigation’; 
import { cookies } from ‘next/headers’;
export async function loginAction(formData: FormData) { 
 const email = formData.get(’email’) as string; 
 const password = formData.get(‘password’) as string;
 // 验证逻辑 
 if (!email || !password) { 
 return { error: ‘Email and password required’ }; 
 }
 // 调用认证服务 
 const response = await fetch(‘https://api.example.com/login’, { 
 method: ‘POST’, 
 body: JSON.stringify({ email, password }), 
 });
 if (!response.ok) { 
 return { error: ‘Invalid credentials’ }; 
 }
 const { token } = await response.json();
 // 设置 cookie 
 cookies().set(‘auth-token’, token, { 
 httpOnly: true, 
 secure: process.env.NODE_ENV === ‘production’, 
 maxAge: 60 * 60 * 24, // 7 days 
 });
 redirect(‘/dashboard’); 
}
export async function logoutAction() { 
 cookies().delete(‘auth-token’); 
 redirect(‘/login’); 
} 
app/login/page.tsx (使用 Server Action): 
import { loginAction } from ‘../actions’;
export default function LoginPage() { 
 return (
<div>
<h1>Login</h1>
<form action={loginAction}>
<div>
 <label>Email:</label> 
 <input type="email" name="email" required />
 </div>
<div>
 <label>Password:</label> 
 <input type="password" name="password" required />
 </div>
 <button type="submit">Login</button> 
 </form>
</div>
 ); 
} 
5.3 处理第三方库和自定义 Hook 
问题 
: 许多第三方库（如 
react-query 
、 
swr 
、 
zustand 
）在 Server Components 中无法直接使用。 
解决方案 
: 将使用这些库的组件标记为 Client Components，并在 Server Components 中组合使用。 
示例：使用 React Query 
app/providers.tsx: 
‘use client’;
import { QueryClient, QueryClientProvider } from ‘@tanstack/react-query’; 
import { useState } from ‘react’;
export function QueryProvider({ children }: { children: React.ReactNode }) { 
 const [queryClient] = useState(() => new QueryClient());
 return ( 
 <QueryClientProvider client={queryClient}> 
 {children} 
 </QueryClientProvider> 
 ); 
} 
app/layout.tsx: 
import { QueryProvider } from ‘./providers’;
export default function RootLayout({ children }: { children: React.ReactNode }) { 
 return ( 
 <html lang="en"> 
 <body> 
 <QueryProvider>{children}</QueryQueryProvider> 
 </body> 
 </html> 
 ); 
} 
app/posts/page.tsx: 
import PostsList from ‘./posts-list’;
export default function PostsPage() { 
 return (
<div>
<h1>Posts</h1>
 <PostsList />
 </div>
 ); 
} 
app/posts/posts-list.tsx: 
‘use client’;
import { useQuery } from ‘@tanstack/react-query’;
export default function PostsList() { 
 const { data, isLoading, error } = useQuery({ 
 queryKey: [‘posts’], 
 queryFn: async () => { 
 const res = await fetch(‘/api/posts’); 
 return res.json(); 
 }, 
 });
 if (isLoading) return 
<div>Loading…</div>
; 
 if (error) return 
<div>Error: {error.message}</div>
;
 return (
<ul>
 {data?.map((post: any) => (
<li key={post.id}>{post.title}</li>
 ))}
 </ul>
 ); 
} 
6. 测试和验证 
6.1 单元测试 
使用 Jest 和 React Testing Library: 
// __tests__/posts-list.test.tsx 
import { render, screen } from ‘@testing-library/react’; 
import PostsList from ‘@/app/posts/posts-list’;
// 模拟 fetch 
global.fetch = jest.fn();
describe(‘PostsList’, () => { 
 it(‘renders posts’, async () => { 
 (fetch as jest.Mock).mockResolvedValue({ 
 ok: true, 
 json: async () => [{ id: 1, title: ‘Test Post’ }], 
 });
 const postsList = await PostsList(); 
 render(postsList);
 expect(screen.getByText(‘Test Post’)).toBeInTheDocument(); 
 }); 
}); 
6.2 端到端测试 
使用 Playwright: 
// e2e/posts.spec.ts 
import { test, expect } from ‘@playwright/test’;
test(‘should navigate to post detail’, async ({ page }) => { 
 await page.goto(‘/posts’); 
 await page.click(‘text=Test Post’); 
 await expect(page).toHaveURL(/\/posts\/\d+/); 
 await expect(page.getByRole(‘heading’)).toContainText(‘Test Post’); 
}); 
7. 性能优化最佳实践 
7.1 减少客户端 JavaScript 
原则 
: 尽可能使用 Server Components，只在必要时使用 Client Components。 
优化前: 
// app/page.tsx – 不必要的 Client Component 
‘use client’;
export default function Home() { 
 return 
<h1>Welcome</h1>
; 
} 
优化后: 
// app/page.tsx – Server Component 
export default function Home() { 
 return 
<h1>Welcome</h1>
; 
} 
7.2 使用 Streaming 和 Suspense 
app/posts/page.tsx: 
import { Suspense } from ‘react’; 
import PostsList from ‘./posts-list’; 
import PostStats from ‘./post-stats’;
export default function PostsPage() { 
 return (
<div>
<h1>Posts</h1>
 <Suspense fallback={

<div>Loading stats…</div>
}> 
 <PostStats /> 
 </Suspense> 
 <Suspense fallback={

<div>Loading posts…</div>
}> 
 <PostsList /> 
 </Suspense>
 </div>
 ); 
} 
7.3 优化数据获取 
使用并行数据获取: 
// app/dashboard/page.tsx 
import { Suspense } from ‘react’;
async function getUserData() { 
 // … 
}
async function getDashboardStats() { 
 // … 
}
export default async function DashboardPage() { 
 // 并行获取数据 
 const [userData, stats] = await Promise.all([ 
 getUserData(), 
 getDashboardStats(), 
 ]);
 return (
<div>
<h1>Dashboard</h1>
 <UserData data={userData} /> 
 <Stats data={stats} />
 </div>
 ); 
} 
8. 常见问题 FAQ 
Q1: 我可以完全不迁移吗？ 
A 
: 可以，Next.js 仍然支持 Pages Router。但 App Router 是未来方向，建议逐步迁移。 
Q2: 迁移需要多长时间？ 
A 
: 小型项目可能只需几天，大型项目可能需要数周甚至数月，取决于代码复杂度和团队规模。 
Q3: 如何处理第三方 UI 库？ 
A 
: 大多数库需要包装在 Client Components 中。检查库的文档，看是否支持 Server Components。 
Q4: 如何处理动态导入（dynamic imports）？ 
A 
: 使用 
next/dynamic 
，但注意它必须在 Client Components 中使用。 
‘use client’;
import dynamic from ‘next/dynamic’;
const HeavyComponent = dynamic(() => import(‘./heavy-component’), { 
 loading: () => 
Loading…
, 
}); 
Q5: 如何处理自定义服务器？ 
A 
: App Router 不支持自定义服务器。需要使用 API 路由或外部服务器。 
9. 迁移检查清单 
在开始迁移前，使用这个检查清单确保准备充分： 
[ ] 升级 Next.js 到 13+ 版本 
[ ] 安装必要的依赖和类型定义 
[ ] 理解 Server Components 和 Client Components 的区别 
[ ] 规划迁移策略（渐进式 vs 一次性） 
[ ] 创建 App Router 基础结构（layout, page, error, loading） 
[ ] 迁移核心页面（从简单页面开始） 
[ ] 处理动态路由和参数 
[ ] 重构数据获取逻辑 
[ ] 设置路由守卫和认证 
[ ] 处理全局状态管理 
[ ] 更新 API 路由 
[ ] 处理第三方库和自定义 Hook 
[ ] 设置错误边界和加载状态 
[ ] 编写测试 
[ ] 性能测试和优化 
[ ] 更新文档和团队培训 
10. 总结 
从 Pages Router 迁移到 App Router 是 Next.js 发展的重要里程碑。虽然迁移过程需要投入时间和精力，但带来的好处是显著的： 
更好的性能 
: 更少的客户端 JavaScript，更快的页面加载 
更灵活的数据获取 
: 细粒度的缓存控制和数据获取策略 
更清晰的架构 
: 明确的服务器/客户端边界 
更好的开发体验 
: 更直观的文件结构和自动代码分割 
迁移的关键是理解新范式，采用渐进式策略，并充分利用 App Router 提供的新特性。记住，这不是一个非此即彼的选择，Next.js 允许两种模式共存，让你可以按照自己的节奏完成迁移。 
开始你的迁移之旅吧！如果遇到问题，Next.js 社区和官方文档都是很好的资源。祝你迁移顺利！
</div>

<nav class="wp-block-group is-content-justification-space-between is-nowrap is-layout-flex wp-container-core-group-is-layout-2b923ac6 wp-block-group-is-layout-flex" style="padding-top:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--40)" aria-label="Posts">
	<div class="post-navigation-link-previous wp-block-post-navigation-link">←<a href="https://ziliao.tiaomu.com/116999532/" rel="prev">Previous: 361智能跑鞋如何解决跑者痛点 智能科技助力提升运动表现与舒适度</a></div>
	<div class="post-navigation-link-next wp-block-post-navigation-link"><a href="https://ziliao.tiaomu.com/116999534/" rel="next">Next: 轻松转换XML Schema，一招生成高效Java类与POJO，提升开发效率！</a>→</div>
</nav>

</div>
		
	</div>
	
</main>

<a href="https://ziliao.tiaomu.com" target="_self" rel="home">资料库 – 中文知识库</a>

</div>
			
		</div>

<div class="wp-block-column is-layout-flow wp-block-column-is-layout-flow" style="flex-basis:50%">
			
			<div class="wp-block-group is-content-justification-space-between is-layout-flex wp-container-core-group-is-layout-cf54d0a6 wp-block-group-is-layout-flex">
				
				<div class="wp-block-group is-vertical is-content-justification-stretch is-layout-flex wp-container-core-group-is-layout-d8dce8eb wp-block-group-is-layout-flex">
					
					<h2 class="wp-block-heading has-medium-font-size has-body-font-family" style="font-style:normal;font-weight:600">About</h2>

<nav style="font-style:normal;font-weight:400" class="has-small-font-size is-vertical wp-block-navigation is-layout-flex wp-container-core-navigation-is-layout-bce0c455 wp-block-navigation-is-layout-flex" aria-label="About"><ul style="font-style:normal;font-weight:400" class="wp-block-navigation__container has-small-font-size is-vertical wp-block-navigation" aria-label="About"><li class="wp-block-navigation-item wp-block-navigation-link"><a class="wp-block-navigation-item__content" href="#">Team</a></li><li class="wp-block-navigation-item wp-block-navigation-link"><a class="wp-block-navigation-item__content" href="#">History</a></li><li class="wp-block-navigation-item wp-block-navigation-link"><a class="wp-block-navigation-item__content" href="#">Careers</a></li></ul></nav>

</div>
					
				</div>

<div class="wp-block-group is-vertical is-content-justification-stretch is-layout-flex wp-container-core-group-is-layout-d8dce8eb wp-block-group-is-layout-flex">
					
					<h2 class="wp-block-heading has-medium-font-size has-body-font-family" style="font-style:normal;font-weight:600">Privacy</h2>

<nav style="font-style:normal;font-weight:400" class="has-small-font-size is-vertical wp-block-navigation is-layout-flex wp-container-core-navigation-is-layout-bce0c455 wp-block-navigation-is-layout-flex" aria-label="Privacy"><ul style="font-style:normal;font-weight:400" class="wp-block-navigation__container has-small-font-size is-vertical wp-block-navigation" aria-label="Privacy"><li class="wp-block-navigation-item wp-block-navigation-link"><a class="wp-block-navigation-item__content" href="#">Privacy Policy</a></li><li class="wp-block-navigation-item wp-block-navigation-link"><a class="wp-block-navigation-item__content" href="#">Terms and Conditions</a></li><li class="wp-block-navigation-item wp-block-navigation-link"><a class="wp-block-navigation-item__content" href="#">Contact Us</a></li></ul></nav>

</div>
					
				</div>

<nav style="font-style:normal;font-weight:400" class="has-small-font-size is-vertical wp-block-navigation is-layout-flex wp-container-core-navigation-is-layout-bce0c455 wp-block-navigation-is-layout-flex" aria-label="Social Media"><ul style="font-style:normal;font-weight:400" class="wp-block-navigation__container has-small-font-size is-vertical wp-block-navigation" aria-label="Social Media"><li class="wp-block-navigation-item wp-block-navigation-link"><a class="wp-block-navigation-item__content" href="#">Facebook</a></li><li class="wp-block-navigation-item wp-block-navigation-link"><a class="wp-block-navigation-item__content" href="#">Instagram</a></li><li class="wp-block-navigation-item wp-block-navigation-link"><a class="wp-block-navigation-item__content" href="#">Twitter/X</a></li></ul></nav>

</div>
					
				</div>
				
			</div>
			
		</div>
		
	</div>

<div class="wp-block-group alignwide is-layout-flow wp-block-group-is-layout-flow" style="padding-top:var(--wp--preset--spacing--50);padding-bottom:0">
		
		
		Designed with <a href="https://wordpress.org" rel="nofollow">WordPress</a>		
		
	</div>
	
</div>

</footer>
</div>
<script type="speculationrules">
{"prefetch":[{"source":"document","where":{"and":[{"href_matches":"/*"},{"not":{"href_matches":["/wp-*.php","/wp-admin/*","/wp-content/uploads/*","/wp-content/*","/wp-content/plugins/*","/wp-content/themes/twentytwentyfour/*","/*\\?(.+)"]}},{"not":{"selector_matches":"a[rel~=\"nofollow\"]"}},{"not":{"selector_matches":".no-prefetch, .no-prefetch a"}}]},"eagerness":"conservative"}]}
</script>
<script data-wp-router-options="{"loadOnClientNavigation":true}" fetchpriority="low" id="@wordpress/block-library/navigation/view-js-module" src="https://ziliao.tiaomu.com/wp-includes/js/dist/script-modules/block-library/navigation/view.min.js?ver=1bf28ded04f9f188bdcb" type="module"></script>
<script id="wp-emoji-settings" type="application/json">
{"baseUrl":"https://s.w.org/images/core/emoji/17.0.2/72x72/","ext":".png","svgUrl":"https://s.w.org/images/core/emoji/17.0.2/svg/","svgExt":".svg","source":{"concatemoji":"https://ziliao.tiaomu.com/wp-includes/js/wp-emoji-release.min.js?ver=7.1.3"}}
</script>
<script type="module">
/*! This file is auto-generated */
var e="script#wp-emoji-settings",t=document.querySelector(e);if(!(t instanceof HTMLScriptElement))throw new Error("Element missing: "+e);const r=JSON.parse(t.text),s=(window._wpemojiSettings=r,"wpEmojiSettingsSupports"),o=["flag","emoji"];function i(e){try{var t={supportTests:e,timestamp:(new Date).valueOf()};sessionStorage.setItem(s,JSON.stringify(t))}catch(e){}}function c(e,t,n){e.clearRect(0,0,e.canvas.width,e.canvas.height),e.fillText(t,0,0);t=new Uint32Array(e.getImageData(0,0,e.canvas.width,e.canvas.height).data);e.clearRect(0,0,e.canvas.width,e.canvas.height),e.fillText(n,0,0);const r=new Uint32Array(e.getImageData(0,0,e.canvas.width,e.canvas.height).data);return t.every((e,t)=>e===r[t])}function p(e,t){e.clearRect(0,0,e.canvas.width,e.canvas.height),e.fillText(t,0,0);var n=e.getImageData(16,16,1,1);for(let e=0;e<n.data.length;e++)if(0!==n.data[e])return!1;return!0}function u(e,t,n,r){switch(t){case"flag":return n(e,"\ud83c\udff3\ufe0f\u200d\u26a7\ufe0f","\ud83c\udff3\ufe0f\u200b\u26a7\ufe0f")?!1:!n(e,"\ud83c\udde8\ud83c\uddf6","\ud83c\udde8\u200b\ud83c\uddf6")&&!n(e,"\ud83c\udff4\udb40\udc67\udb40\udc62\udb40\udc65\udb40\udc6e\udb40\udc67\udb40\udc7f","\ud83c\udff4\u200b\udb40\udc67\u200b\udb40\udc62\u200b\udb40\udc65\u200b\udb40\udc6e\u200b\udb40\udc67\u200b\udb40\udc7f");case"emoji":return!r(e,"\ud83e\u1fac8")}return!1}function f(e,t,n,r){let a;const s=(a="undefined"!=typeof WorkerGlobalScope&&self instanceof WorkerGlobalScope?new OffscreenCanvas(300,150):document.createElement("canvas")).getContext("2d",{willReadFrequently:!0}),o=(s.textBaseline="top",s.font="600 32px Arial",{});return e.forEach(e=>{o[e]=t(s,e,n,r)}),o}function a(e){var t=document.createElement("script");t.src=e,t.defer=!0,document.head.appendChild(t)}r.supports={everything:!0,everythingExceptFlag:!0},new Promise(t=>{let n=function(){try{var e=JSON.parse(sessionStorage.getItem(s));if("object"==typeof e&&"number"==typeof e.timestamp&&(new Date).valueOf()<e.timestamp+604800&&"object"==typeof e.supportTests)return e.supportTests}catch(e){}return null}();if(!n){if("undefined"!=typeof Worker&&"undefined"!=typeof OffscreenCanvas&&"undefined"!=typeof URL&&URL.createObjectURL&&"undefined"!=typeof Blob)try{var e="postMessage("+f.toString()+"("+[JSON.stringify(o),u.toString(),c.toString(),p.toString()].join(",")+"));",r=new Blob([e],{type:"text/javascript"});const a=new Worker(URL.createObjectURL(r),{name:"wpTestEmojiSupports"});return void(a.onmessage=e=>{i(n=e.data),a.terminate(),t(n)})}catch(e){}i(n=f(o,u,c,p))}t(n)}).then(e=>{for(const n in e)r.supports[n]=e[n],r.supports.everything=r.supports.everything&&r.supports[n],"flag"!==n&&(r.supports.everythingExceptFlag=r.supports.everythingExceptFlag&&r.supports[n]);var t;r.supports.everythingExceptFlag=r.supports.everythingExceptFlag&&!r.supports.flag,r.supports.everything||((t=r.source||{}).concatemoji?a(t.concatemoji):t.wpemoji&&t.twemoji&&(a(t.twemoji),a(t.wpemoji)))});
//# sourceURL=https://ziliao.tiaomu.com/wp-includes/js/wp-emoji-loader.min.js
</script>
<noscript><link rel="stylesheet" href="https://ziliao.tiaomu.com/wp-content/themes/abiz/assets/css/all.min.css?ver=6.5.1"></noscript>
</body>
</html>

Next.js 13 App Router 全面升级指南 从 Pages 到 App 模式如何快速上手并解决常见迁移难题

Welcome to the new App Router

All Posts

{post.title}

Next.js 13 App Router 全面升级指南从 Pages 到 App 模式如何快速上手并解决常见迁移难题