App Router 增量采用指南

本指南将帮助你

将你的 Next.js 应用程序从版本 12 更新到版本 13
升级在 pages 和 app 目录中都适用的功能
将你现有的应用程序从 pages 增量迁移到 app

升级

Node.js 版本

最低 Node.js 版本现在是 v18.17。请参阅 Node.js 文档以获取更多信息。

Next.js 版本

要更新到 Next.js 版本 13，请使用你偏好的包管理器运行以下命令

终端

npm install next@latest react@latest react-dom@latest

ESLint 版本

如果你正在使用 ESLint，则需要升级你的 ESLint 版本

终端

npm install -D eslint-config-next@latest

须知：你可能需要在 VS Code 中重启 ESLint 服务器，以使 ESLint 更改生效。打开命令面板（Mac 上为 cmd+shift+p；Windows 上为 ctrl+shift+p），并搜索 ESLint: Restart ESLint Server。

下一步

更新后，请参阅以下部分了解后续步骤

升级新功能：本指南帮助你升级到新功能，例如改进的 Image 和 Link 组件。
从 pages 目录迁移到 app 目录：分步指南，帮助你从 pages 目录增量迁移到 app 目录。

升级新功能

Next.js 13 引入了新的 App Router，其中包含新功能和约定。新的 Router 在 app 目录中可用，并与 pages 目录共存。

升级到 Next.js 13 不要求使用 App Router。你可以继续使用 pages 以及在两个目录中都适用的新功能，例如更新后的 Image 组件、Link 组件、Script 组件和字体优化。

`<Image/>` 组件

Next.js 12 为 Image 组件引入了新的改进，并使用了临时导入：next/future/image。这些改进包括减少客户端 JavaScript、更轻松地扩展和设置图像样式、更好的可访问性以及原生浏览器懒加载。

在版本 13 中，这种新行为现在是 next/image 的默认行为。

有两个 codemod 可以帮助你迁移到新的 Image 组件

next-image-to-legacy-image codemod：安全且自动地将 next/image 导入重命名为 next/legacy/image。现有组件将保持相同的行为。
next-image-experimental codemod：危险地添加内联样式并删除未使用的 props。这将更改现有组件的行为以匹配新的默认值。要使用此 codemod，你需要先运行 next-image-to-legacy-image codemod。

`<Link>` 组件

<Link> 组件不再需要手动添加 <a> 标签作为子元素。此行为在版本 12.2 中作为实验性选项添加，现在是默认行为。在 Next.js 13 中，<Link> 始终渲染 <a>，并允许你将 props 转发到底层标签。

例如

import Link from 'next/link'
 
// Next.js 12: `<a>` has to be nested otherwise it's excluded
<Link href="/about">
  <a>About</a>
</Link>
 
// Next.js 13: `<Link>` always renders `<a>` under the hood
<Link href="/about">
  About
</Link>

要将你的链接升级到 Next.js 13，你可以使用 new-link codemod。

`<Script>` 组件

next/script 的行为已更新为同时支持 pages 和 app，但需要进行一些更改以确保平滑迁移

将你之前包含在 _document.js 中的任何 beforeInteractive 脚本移动到根布局文件 (app/layout.tsx)。
实验性的 worker 策略尚不适用于 app，并且标有此策略的脚本要么必须删除，要么必须修改为使用不同的策略（例如 lazyOnload）。
onLoad、onReady 和 onError 处理程序在服务器组件中不起作用，因此请确保将它们移动到客户端组件或完全删除它们。

字体优化

以前，Next.js 通过内联字体 CSS 来帮助你优化字体。版本 13 引入了新的 next/font 模块，使你能够自定义字体加载体验，同时仍能确保出色的性能和隐私。 next/font 在 pages 和 app 目录中均受支持。

虽然内联 CSS 在 pages 中仍然有效，但在 app 中无效。你应该改用 next/font。

请参阅字体优化页面，了解如何使用 next/font。

从 `pages` 迁移到 `app`

🎥 观看： 了解如何增量采用 App Router → YouTube (16 分钟)。

迁移到 App Router 可能是首次使用 Next.js 构建在其之上的 React 功能，例如服务器组件、Suspense 等。当与 Next.js 的新功能（例如特殊文件和布局）结合使用时，迁移意味着需要学习新的概念、心智模型和行为变化。

我们建议通过将迁移分解为更小的步骤来降低这些更新的综合复杂性。 app 目录旨在与 pages 目录同时工作，以允许逐页增量迁移。

app 目录支持嵌套路由和布局。了解更多。
使用嵌套文件夹定义路由，并使用特殊的 page.js 文件使路由段公开访问。了解更多。
特殊文件约定用于为每个路由段创建 UI。最常见的特殊文件是 page.js 和 layout.js。
- 使用 page.js 定义路由独有的 UI。
- 使用 layout.js 定义跨多个路由共享的 UI。
- .js、.jsx 或 .tsx 文件扩展名可用于特殊文件。
你可以在 app 目录内并置其他文件，例如组件、样式、测试等。了解更多。
数据获取函数（如 getServerSideProps 和 getStaticProps）已被 app 内的新 API 替换。 getStaticPaths 已被 generateStaticParams 替换。
pages/_app.js 和 pages/_document.js 已被单个 app/layout.js 根布局替换。了解更多。
pages/_error.js 已被更精细的 error.js 特殊文件替换。了解更多。
pages/404.js 已被 not-found.js 文件替换。
pages/api/* API 路由已被 route.js (路由处理程序) 特殊文件替换。

步骤 2：创建根布局

在 app 目录内创建一个新的 app/layout.tsx 文件。这是一个根布局，将应用于 app 内的所有路由。

app/layout.tsx

export default function RootLayout({
  // Layouts must accept a children prop.
  // This will be populated with nested layouts or pages
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

app 目录必须包含根布局。
根布局必须定义 <html> 和 <body> 标签，因为 Next.js 不会自动创建它们
根布局替换了 pages/_app.tsx 和 pages/_document.tsx 文件。
.js、.jsx 或 .tsx 扩展名可用于布局文件。

要管理 <head> HTML 元素，你可以使用内置的 SEO 支持

app/layout.tsx

import type { Metadata } from 'next'
 
export const metadata: Metadata = {
  title: 'Home',
  description: 'Welcome to Next.js',
}

迁移 `_document.js` 和 `_app.js`

如果你有现有的 _app 或 _document 文件，你可以将内容（例如全局样式）复制到根布局 (app/layout.tsx)。 app/layout.tsx 中的样式将不应用于 pages/*。在迁移到 app 时，你应该保留 _app/_document，以防止你的 pages/* 路由中断。完全迁移后，你可以安全地删除它们。

如果你正在使用任何 React Context 提供程序，则需要将它们移动到客户端组件。

将 `getLayout()` 模式迁移到布局（可选）

Next.js 建议向页面组件添加属性，以在 pages 目录中实现每页布局。此模式可以替换为 app 目录中对嵌套布局的原生支持。

查看迁移前后的示例

迁移前

components/DashboardLayout.js

export default function DashboardLayout({ children }) {
  return (
    <div>
      <h2>My Dashboard</h2>
      {children}
    </div>
  )
}

pages/dashboard/index.js

import DashboardLayout from '../components/DashboardLayout'
 
export default function Page() {
  return <p>My Page</p>
}
 
Page.getLayout = function getLayout(page) {
  return <DashboardLayout>{page}</DashboardLayout>
}

迁移后

从 pages/dashboard/index.js 中删除 Page.getLayout 属性，并按照迁移 Pages 的步骤迁移到 app 目录。
app/dashboard/page.js
```
export default function Page() {
  return <p>My Page</p>
}
```

将 DashboardLayout 的内容移动到新的客户端组件，以保留 pages 目录行为。

app/dashboard/DashboardLayout.js

'use client' // this directive should be at top of the file, before any imports.
 
// This is a Client Component
export default function DashboardLayout({ children }) {
  return (
    <div>
      <h2>My Dashboard</h2>
      {children}
    </div>
  )
}

将 DashboardLayout 导入到 app 目录内的新 layout.js 文件中。

app/dashboard/layout.js

import DashboardLayout from './DashboardLayout'
 
// This is a Server Component
export default function Layout({ children }) {
  return <DashboardLayout>{children}</DashboardLayout>
}

你可以逐步将 DashboardLayout.js（客户端组件）的非交互部分移动到 layout.js（服务器组件）中，以减少发送到客户端的组件 JavaScript 的数量。

步骤 4：迁移 Pages

app 目录中的 Pages 默认是服务器组件。这与 pages 目录不同，在 pages 目录中，页面是客户端组件。
数据获取在 app 中已更改。 getServerSideProps、getStaticProps 和 getInitialProps 已被更简单的 API 替换。
app 目录使用嵌套文件夹来定义路由，并使用特殊的 page.js 文件使路由段公开访问。
pages 目录 app 目录路由
index.js page.js /
about.js about/page.js /about
blog/[slug].js blog/[slug]/page.js /blog/post-1

`pages` 目录	`app` 目录	路由
`index.js`	`page.js`	`/`
`about.js`	`about/page.js`	`/about`
`blog/[slug].js`	`blog/[slug]/page.js`	`/blog/post-1`

我们建议将页面的迁移分解为两个主要步骤

步骤 1：将默认导出的页面组件移动到新的客户端组件。
步骤 2：将新的客户端组件导入到 app 目录内的新 page.js 文件中。

须知：这是最简单的迁移路径，因为它具有与 pages 目录最相似的行为。

步骤 1：创建一个新的客户端组件

在 app 目录内创建一个新的单独文件（即 app/home-page.tsx 或类似文件），该文件导出客户端组件。要定义客户端组件，请将 'use client' 指令添加到文件顶部（在任何导入之前）。
- 与 Pages Router 类似，有一个优化步骤，用于在初始页面加载时将客户端组件预渲染为静态 HTML。
将默认导出的页面组件从 pages/index.js 移动到 app/home-page.tsx。

app/home-page.tsx

'use client'
 
// This is a Client Component (same as components in the `pages` directory)
// It receives data as props, has access to state and effects, and is
// prerendered on the server during the initial page load.
export default function HomePage({ recentPosts }) {
  return (
    <div>
      {recentPosts.map((post) => (
        <div key={post.id}>{post.title}</div>
      ))}
    </div>
  )
}

步骤 2：创建一个新页面

在 app 目录内创建一个新的 app/page.tsx 文件。默认情况下，这是一个服务器组件。
将 home-page.tsx 客户端组件导入到页面中。

如果你在 pages/index.js 中获取数据，请使用新的数据获取 API 将数据获取逻辑直接移动到服务器组件中。有关更多详细信息，请参阅数据获取升级指南。

app/page.tsx

// Import your Client Component
import HomePage from './home-page'
 
async function getPosts() {
  const res = await fetch('https://...')
  const posts = await res.json()
  return posts
}
 
export default async function Page() {
  // Fetch data directly in a Server Component
  const recentPosts = await getPosts()
  // Forward fetched data to your Client Component
  return <HomePage recentPosts={recentPosts} />
}

如果你的上一页使用了 useRouter，则需要更新到新的路由 hooks。了解更多。
启动你的开发服务器并访问 https://127.0.0.1:3000。你应该看到你现有的 index 路由，现在通过 app 目录提供。

步骤 5：迁移路由 Hooks

已添加新的路由器以支持 app 目录中的新行为。

在 app 中，你应该使用从 next/navigation 导入的三个新 hooks：useRouter()、usePathname() 和 useSearchParams()。

新的 useRouter hook 是从 next/navigation 导入的，并且与 pages 中的 useRouter hook（从 next/router 导入）具有不同的行为。
- useRouter hook 从 next/router 导入在 app 目录中不受支持，但可以继续在 pages 目录中使用。
新的 useRouter 不返回 pathname 字符串。请改用单独的 usePathname hook。
新的 useRouter 不返回 query 对象。搜索参数和动态路由参数现在是分开的。请改用 useSearchParams 和 useParams hooks。
你可以将 useSearchParams 和 usePathname 结合使用以监听页面更改。有关更多详细信息，请参阅路由器事件部分。
这些新的 hooks 仅在客户端组件中受支持。它们不能在服务器组件中使用。

app/example-client-component.tsx

'use client'
 
import { useRouter, usePathname, useSearchParams } from 'next/navigation'
 
export default function ExampleClientComponent() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()
 
  // ...
}

此外，新的 useRouter hook 具有以下更改

isFallback 已被删除，因为 fallback 已被替换。
locale、locales、defaultLocales、domainLocales 值已被删除，因为内置 i18n Next.js 功能在 app 目录中不再必要。了解有关 i18n 的更多信息。
basePath 已被删除。替代方案不会成为 useRouter 的一部分。它尚未实现。
asPath 已被移除，因为新的路由已移除 as 的概念。
isReady 已被移除，因为它不再必要。在静态渲染期间，任何使用 useSearchParams() hook 的组件都将跳过预渲染步骤，而是在客户端运行时渲染。
route 已被移除。usePathname 或 useSelectedLayoutSegments() 提供了替代方案。

查看 useRouter() API 参考.

为了保持 pages 和 app 路由之间组件的兼容性，请参考来自 next/compat/router 的 useRouter hook。这是来自 pages 目录的 useRouter hook，但旨在用于在路由器之间共享组件。一旦你准备好仅在 app 路由器上使用它，请更新到来自 next/navigation 的新的 useRouter。

步骤 6：迁移数据获取方法

pages 目录使用 getServerSideProps 和 getStaticProps 来获取页面的数据。在 app 目录中，这些之前的数据获取函数被一个更简单的 API 替代，该 API 构建于 fetch() 和 async React Server Components 之上。

app/page.tsx

export default async function Page() {
  // This request should be cached until manually invalidated.
  // Similar to `getStaticProps`.
  // `force-cache` is the default and can be omitted.
  const staticData = await fetch(`https://...`, { cache: 'force-cache' })
 
  // This request should be refetched on every request.
  // Similar to `getServerSideProps`.
  const dynamicData = await fetch(`https://...`, { cache: 'no-store' })
 
  // This request should be cached with a lifetime of 10 seconds.
  // Similar to `getStaticProps` with the `revalidate` option.
  const revalidatedData = await fetch(`https://...`, {
    next: { revalidate: 10 },
  })
 
  return <div>...</div>
}

服务端渲染 (`getServerSideProps`)

在 pages 目录中，getServerSideProps 用于在服务器上获取数据，并将 props 转发到文件中默认导出的 React 组件。页面的初始 HTML 从服务器预渲染，然后在浏览器中“水合”（使其可交互）。

pages/dashboard.js

// `pages` directory
 
export async function getServerSideProps() {
  const res = await fetch(`https://...`)
  const projects = await res.json()
 
  return { props: { projects } }
}
 
export default function Dashboard({ projects }) {
  return (
    <ul>
      {projects.map((project) => (
        <li key={project.id}>{project.name}</li>
      ))}
    </ul>
  )
}

在 App Router 中，我们可以使用 Server Components 将数据获取与 React 组件放在一起。这允许我们向客户端发送更少的 JavaScript，同时保持从服务器渲染的 HTML。

通过将 cache 选项设置为 no-store，我们可以表明获取的数据应永远不被缓存。这类似于 pages 目录中的 getServerSideProps。

app/dashboard/page.tsx

// `app` directory
 
// This function can be named anything
async function getProjects() {
  const res = await fetch(`https://...`, { cache: 'no-store' })
  const projects = await res.json()
 
  return projects
}
 
export default async function Dashboard() {
  const projects = await getProjects()
 
  return (
    <ul>
      {projects.map((project) => (
        <li key={project.id}>{project.name}</li>
      ))}
    </ul>
  )
}

访问 Request 对象

在 pages 目录中，你可以基于 Node.js HTTP API 检索基于请求的数据。

例如，你可以从 getServerSideProps 中检索 req 对象，并使用它来检索请求的 cookies 和 headers。

pages/index.js

// `pages` directory
 
export async function getServerSideProps({ req, query }) {
  const authHeader = req.getHeaders()['authorization'];
  const theme = req.cookies['theme'];
 
  return { props: { ... }}
}
 
export default function Page(props) {
  return ...
}

app 目录公开了新的只读函数来检索请求数据

headers：基于 Web Headers API，可以在 Server Components 内部使用，以检索请求 headers。
cookies：基于 Web Cookies API，可以在 Server Components 内部使用，以检索 cookies。

app/page.tsx

// `app` directory
import { cookies, headers } from 'next/headers'
 
async function getData() {
  const authHeader = (await headers()).get('authorization')
 
  return '...'
}
 
export default async function Page() {
  // You can use `cookies` or `headers` inside Server Components
  // directly or in your data fetching function
  const theme = (await cookies()).get('theme')
  const data = await getData()
  return '...'
}

静态站点生成 (`getStaticProps`)

在 pages 目录中，getStaticProps 函数用于在构建时预渲染页面。此函数可用于从外部 API 或直接从数据库获取数据，并在构建期间生成页面时将此数据传递到整个页面。

pages/index.js

// `pages` directory
 
export async function getStaticProps() {
  const res = await fetch(`https://...`)
  const projects = await res.json()
 
  return { props: { projects } }
}
 
export default function Index({ projects }) {
  return projects.map((project) => <div>{project.name}</div>)
}

在 app 目录中，使用 fetch() 进行数据获取将默认使用 cache: 'force-cache'，这将缓存请求数据直到手动失效。这类似于 pages 目录中的 getStaticProps。

app/page.js

// `app` directory
 
// This function can be named anything
async function getProjects() {
  const res = await fetch(`https://...`)
  const projects = await res.json()
 
  return projects
}
 
export default async function Index() {
  const projects = await getProjects()
 
  return projects.map((project) => <div>{project.name}</div>)
}

动态路径 (`getStaticPaths`)

在 pages 目录中，getStaticPaths 函数用于定义应在构建时预渲染的动态路径。

pages/posts/[id].js

// `pages` directory
import PostLayout from '@/components/post-layout'
 
export async function getStaticPaths() {
  return {
    paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
  }
}
 
export async function getStaticProps({ params }) {
  const res = await fetch(`https://.../posts/${params.id}`)
  const post = await res.json()
 
  return { props: { post } }
}
 
export default function Post({ post }) {
  return <PostLayout post={post} />
}

在 app 目录中，getStaticPaths 被 generateStaticParams 替代。

generateStaticParams 的行为类似于 getStaticPaths，但具有简化的 API 用于返回路由参数，并且可以在 layouts 内部使用。generateStaticParams 的返回结构是一个 segments 数组，而不是嵌套的 param 对象数组或已解析路径的字符串。

app/posts/[id]/page.js

// `app` directory
import PostLayout from '@/components/post-layout'
 
export async function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }]
}
 
async function getPost(params) {
  const res = await fetch(`https://.../posts/${(await params).id}`)
  const post = await res.json()
 
  return post
}
 
export default async function Post({ params }) {
  const post = await getPost(params)
 
  return <PostLayout post={post} />
}

对于 app 目录中的新模型，使用名称 generateStaticParams 比 getStaticPaths 更合适。get 前缀被更具描述性的 generate 替代，现在 getStaticProps 和 getServerSideProps 不再必要，单独使用 generate 更好。“Paths”后缀被 “Params” 替代，后者更适合具有多个动态 segments 的嵌套路由。

替换 `fallback`

在 pages 目录中，从 getStaticPaths 返回的 fallback 属性用于定义未在构建时预渲染的页面的行为。此属性可以设置为 true 以显示 fallback 页面，同时生成页面，设置为 false 以显示 404 页面，或设置为 blocking 以在请求时生成页面。

pages/posts/[id].js

// `pages` directory
 
export async function getStaticPaths() {
  return {
    paths: [],
    fallback: 'blocking'
  };
}
 
export async function getStaticProps({ params }) {
  ...
}
 
export default function Post({ post }) {
  return ...
}

在 app 目录中，config.dynamicParams 属性控制如何处理 generateStaticParams 之外的 params

true：（默认）未包含在 generateStaticParams 中的动态 segments 将按需生成。
false：未包含在 generateStaticParams 中的动态 segments 将返回 404。

这替换了 pages 目录中 getStaticPaths 的 fallback: true | false | 'blocking' 选项。dynamicParams 中不包含 fallback: 'blocking' 选项，因为使用流式传输时，'blocking' 和 true 之间的差异可以忽略不计。

app/posts/[id]/page.js

// `app` directory
 
export const dynamicParams = true;
 
export async function generateStaticParams() {
  return [...]
}
 
async function getPost(params) {
  ...
}
 
export default async function Post({ params }) {
  const post = await getPost(params);
 
  return ...
}

当 dynamicParams 设置为 true（默认值）时，当请求尚未生成的路由 segment 时，它将被服务端渲染并缓存。

增量静态再生 (`getStaticProps` 与 `revalidate`)

在 pages 目录中，getStaticProps 函数允许你添加 revalidate 字段，以在一定时间后自动重新生成页面。

pages/index.js

// `pages` directory
 
export async function getStaticProps() {
  const res = await fetch(`https://.../posts`)
  const posts = await res.json()
 
  return {
    props: { posts },
    revalidate: 60,
  }
}
 
export default function Index({ posts }) {
  return (
    <Layout>
      <PostList posts={posts} />
    </Layout>
  )
}

在 app 目录中，使用 fetch() 进行数据获取可以使用 revalidate，这将把请求缓存指定的秒数。

app/page.js

// `app` directory
 
async function getPosts() {
  const res = await fetch(`https://.../posts`, { next: { revalidate: 60 } })
  const data = await res.json()
 
  return data.posts
}
 
export default async function PostList() {
  const posts = await getPosts()
 
  return posts.map((post) => <div>{post.name}</div>)
}

API 路由

API 路由在 pages/api 目录中继续工作，没有任何更改。但是，它们在 app 目录中已被 Route Handlers 替代。

Route Handlers 允许你使用 Web Request 和 Response API 为给定路由创建自定义请求处理程序。

app/api/route.ts

export async function GET(request: Request) {}

须知：如果你之前使用 API 路由从客户端调用外部 API，你现在可以使用 Server Components 代替以安全地获取数据。了解更多关于数据获取的信息。

module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}', // <-- Add this line
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
  ],
}

你还需要在你的 app/layout.js 文件中导入你的全局样式

app/layout.js

import '../styles/globals.css'
 
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

了解更多关于使用 Tailwind CSS 进行样式设置的信息

将 App Router 与 Pages Router 一起使用

当在由不同的 Next.js 路由器提供的路由之间导航时，将发生硬导航。使用 next/link 的自动链接预取将不会跨路由器预取。

相反，你可以优化 App Router 和 Pages Router 之间的导航，以保留预取的和快速的页面过渡。了解更多。

Codemods

Next.js 提供了 Codemod 转换，以帮助在功能被弃用时升级你的代码库。有关更多信息，请参阅 Codemods。

App Router 增量采用指南

升级

Node.js 版本

Next.js 版本

ESLint 版本

下一步

升级新功能

`<Image/>` 组件

`<Link>` 组件

`<Script>` 组件

字体优化

从 `pages` 迁移到 `app`

步骤 1：创建 `app` 目录

步骤 2：创建根布局

迁移 `_document.js` 和 `_app.js`

将 `getLayout()` 模式迁移到布局（可选）

步骤 3：迁移 `next/head`

步骤 4：迁移 Pages

步骤 5：迁移路由 Hooks

步骤 6：迁移数据获取方法

服务端渲染 (`getServerSideProps`)

访问 Request 对象

静态站点生成 (`getStaticProps`)

动态路径 (`getStaticPaths`)

替换 `fallback`

增量静态再生 (`getStaticProps` 与 `revalidate`)

API 路由

单页应用程序

步骤 7：样式

Tailwind CSS

将 App Router 与 Pages Router 一起使用

Codemods