NNext.js 中文网 GitHub

如何从 Pages 迁移到 App Router

了解如何将现有的 Next.js 应用程序从 Pages Router 升级到 App Router。

本指南将帮助你:

升级#

Node.js 版本#

最低 Node.js 版本现在为 v18.17。有关更多信息,请参阅 Node.js 文档。

Next.js 版本#

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

bash · pnpm
pnpm add next@latest react@latest react-dom@latest
bash · npm
npm install next@latest react@latest react-dom@latest
bash · yarn
yarn add next@latest react@latest react-dom@latest
bash · bun
bun add next@latest react@latest react-dom@latest

ESLint 版本#

如果你使用 ESLint,则需要升级 ESLint 版本:

bash · pnpm
pnpm add -D eslint-config-next@latest
bash · npm
npm install -D eslint-config-next@latest
bash · yarn
yarn add -D eslint-config-next@latest
bash · bun
bun add -D eslint-config-next@latest

小知识:你可能需要在 VS Code 中重启 ESLint 服务器,ESLint 的更改才会生效。打开命令面板(Mac 上为 cmd+shift+p;Windows 上为 ctrl+shift+p)并搜索 ESLint: Restart ESLint Server。

后续步骤#

更新完成后,请参阅以下小节了解后续步骤:

升级新功能#

Next.js 13 引入了新的 App Router,带有新的功能和约定。新的 Router 位于 app 目录中,并与 pages 目录共存。

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

<Image/> 组件#

Next.js 12 通过临时导入 next/future/image 引入了对 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 转发给底层标签。

例如:

jsx
import Link from 'next/link'

// Next.js 12: 必须嵌套 `<a>`,否则它会被排除
<Link href="/about">
  <a>About</a>
</Link>

// Next.js 13: `<Link>` 始终在底层渲染 `<a>`
<Link href="/about">
  About
</Link>

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

<Script> 组件#

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

  • 将你之前包含在 _document.js 中的任何 beforeInteractive 脚本移动到根布局中,例如 app/layout.tsx 或 app/[locale]/layout.tsx。
  • 实验性的 worker 策略尚不能在 app 中工作,使用此策略标记的脚本必须移除,或修改以使用其他策略(例如 lazyOnload)。
  • onLoad、onReady 和 onError 处理器在 Server Component 中不起作用,因此请务必将它们移动到 Client Component 或将其完全移除。

字体优化#

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

虽然内联 CSS 在 pages 中仍然有效,但它在 app 中不起作用。你应改用 next/font。

请参阅 Font Optimization 页面,了解如何使用 next/font。

从 pages 迁移到 app#

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

迁移到 App Router 可能是你首次使用 Next.js 构建于其上方的 React 功能,例如 Server Component、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 已被 route.js(Route Handler)特殊文件取代。

第 1 步:创建 app 目录#

更新到最新的 Next.js 版本(需要 13.4 或更高版本):

bash · pnpm
pnpm add next@latest
bash · npm
npm install next@latest
bash · yarn
yarn add next@latest
bash · bun
bun add next@latest

然后,在项目根目录(或 src/ 目录)中创建一个新的 app 目录。

第 2 步:创建根布局#

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

app/layout.tsx
export default function RootLayout({
  // 布局必须接受 children prop。
  // 它将由嵌套的布局或页面填充
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}
app/layout.js
export default function RootLayout({
  // 布局必须接受 children prop。
  // 它将由嵌套的布局或页面填充
  children,
}) {
  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',
}
app/layout.js
export const metadata = {
  title: 'Home',
  description: 'Welcome to Next.js',
}

迁移 _document.js 和 _app.js#

如果你有现有的 _app 或 _document 文件,可以将其内容(例如全局样式)复制到根布局(app/layout.tsx)中。app/layout.tsx 中的样式将不会应用于 pages/*。在迁移期间,你应保留 _app/_document,以防止 pages/* 路由被破坏。完全迁移后,便可以安全地删除它们。

如果你使用了任何 React Context provider,则需要将它们移动到 Client Component。

将 getLayout() 模式迁移为布局(可选)#

Next.js 曾建议向 Page 组件添加属性,以在 pages 目录中实现逐页布局。这种模式可以用 app 目录中对嵌套布局的原生支持来替代。

<details> <summary>查看迁移前后的示例</summary>

之前

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 属性,并按照迁移页面的步骤迁移到 app 目录。

```jsx filename="app/dashboard/page.js" export default function Page() {

return <p>My Page</p>

} ```

  • 将 DashboardLayout 的内容移动到新的 Client Component 中,以保留 pages 目录的行为。

```jsx filename="app/dashboard/DashboardLayout.js" 'use client' // 此指令应位于文件顶部,在任何导入之前。

// 这是一个 Client Component export default function DashboardLayout({ children }) {

return (
  <div>
    <h2>My Dashboard</h2>
    {children}
  </div>
)

} ```

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

```jsx filename="app/dashboard/layout.js" import DashboardLayout from './DashboardLayout'

// 这是一个 Server Component export default function Layout({ children }) {

return <DashboardLayout>{children}</DashboardLayout>

} ```

  • 你可以增量地将 DashboardLayout.js(Client Component)中非交互的部分移动到 layout.js(Server Component),以减少发送给客户端的组件 JavaScript 数量。

</details>

第 3 步:迁移 next/head#

在 pages 目录中,next/head React 组件用于管理 <head> HTML 元素,例如 title 和 meta。在 app 目录中,next/head 已被新的内置 SEO 支持取代。

之前:

pages/index.tsx
import Head from 'next/head'

export default function Page() {
  return (
    <>
      <Head>
        <title>My page title</title>
      </Head>
    </>
  )
}
pages/index.js
import Head from 'next/head'

export default function Page() {
  return (
    <>
      <Head>
        <title>My page title</title>
      </Head>
    </>
  )
}

之后:

app/page.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'My Page Title',
}

export default function Page() {
  return '...'
}
app/page.js
export const metadata = {
  title: 'My Page Title',
}

export default function Page() {
  return '...'
}

查看所有 metadata 选项。

第 4 步:迁移页面#

  • app 目录中的页面默认是 Server Component。这不同于 pages 目录,其中页面是 Client Component。
  • 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 |

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

  • 第 1 步:将默认导出的 Page 组件移动到一个新的 Client Component 中。
  • 第 2 步:将新的 Client Component 导入 app 目录中新的 page.js 文件。

小知识:这是最简单的迁移路径,因为它的行为与 pages 目录最具可比性。

第 1 步:创建新的 Client Component

  • 在 app 目录中创建一个新的独立文件(即 app/home-page.tsx 或类似文件),用于导出 Client Component。要定义 Client Component,请在文件顶部(任何导入之前)添加 'use client' 指令。
    • 与 Pages Router 类似,在初始页面加载时,存在一个优化步骤可将 Client Component 预渲染为静态 HTML。
  • 将 pages/index.js 中默认导出的页面组件移动到 app/home-page.tsx。
app/home-page.tsx
'use client'

// 这是一个 Client Component(与 `pages` 目录中的组件相同)
// 它通过 props 接收数据,可以访问 state 和 effects,并且
// 在初始页面加载期间在服务端被预渲染。
export default function HomePage({ recentPosts }) {
  return (
    <div>
      {recentPosts.map((post) => (
        <div key={post.id}>{post.title}</div>
      ))}
    </div>
  )
}
app/home-page.js
'use client'

// 这是一个 Client Component。它接收数据作为 props,
// 并且可以像 `pages` 目录中的 Page 组件一样
// 访问 state 和 effects。
export default function HomePage({ recentPosts }) {
  return (
    <div>
      {recentPosts.map((post) => (
        <div key={post.id}>{post.title}</div>
      ))}
    </div>
  )
}

第 2 步:创建新页面

  • 在 app 目录中创建一个新的 app/page.tsx 文件。它默认是一个 Server Component。
  • 将 home-page.tsx Client Component 导入该页面。
  • 如果你之前在 pages/index.js 中获取数据,请使用新的数据获取 API 将数据获取逻辑直接移入 Server Component。更多详情请参阅数据获取升级指南。

```tsx filename="app/page.tsx" switcher // 导入你的 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() {

// 直接在 Server Component 中获取数据
const recentPosts = await getPosts()
// 将获取到的数据转发给你的 Client Component
return <HomePage recentPosts={recentPosts} />

} ```

```jsx filename="app/page.js" switcher // 导入你的 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() {

// 直接在 Server Component 中获取数据
const recentPosts = await getPosts()
// 将获取到的数据转发给你的 Client Component
return <HomePage recentPosts={recentPosts} />

} ```

  • 如果你的旧页面使用了 useRouter,则需要更新为新的路由 hook。了解更多。
  • 启动开发服务器并访问 http://localhost:3000。你应该会看到现有的索引路由,现在它由 app 目录提供服务。

第 5 步:迁移路由 Hook#

添加了一个新的 router 以支持 app 目录中的新行为。

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

  • 新的 useRouter hook 从 next/navigation 导入,其行为不同于 pages 中从 next/router 导入的 useRouter hook。
  • 新的 useRouter 不返回 pathname 字符串。请改用单独的 usePathname hook。
  • 新的 useRouter 不返回 query 对象。搜索参数和动态路由参数现在是分离的。请改用 useSearchParams 和 useParams hook。
  • 你可以一起使用 useSearchParams 和 usePathname 来监听页面变化。有关更多详情,请参阅 Router 事件部分。
  • 这些新 hook 仅在 Client Component 中受支持,不能在 Server Component 中使用。
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()

  // ...
}
app/example-client-component.js
'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、defaultLocale、domainLocales 值已被移除,因为 app 目录中不再需要 Next.js 内置的 i18n 功能。了解更多关于 i18n 的信息。
  • basePath 已被移除。替代方案不会成为 useRouter 的一部分。它尚未实现。
  • asPath 已被移除,因为新 router 中已移除 as 的概念。
  • isReady 已被移除,因为不再需要它。在预渲染期间,任何使用 useSearchParams() hook 的组件都会跳过预渲染步骤,改为在运行时在客户端渲染。
  • route 已被移除。usePathname 或 useSelectedLayoutSegments() 提供了替代方案。
  • router.push() 和 router.replace() 不再返回 Promise。它们会将路由更改排队为 React Transition 并立即返回。要显示待处理状态,请在 useTransition 返回的 startTransition 中调用它们,并读取 isPending。有关示例,请参阅带待处理反馈的筛选。

查看 useRouter() API 参考。

在 pages 和 app 之间共享组件#

要使组件在 pages 和 app router 之间保持兼容,请参阅来自 next/compat/router 的 useRouter hook。

这是来自 pages 目录的 useRouter hook,但用于在 router 之间共享组件时使用。当你准备好只在 app router 上使用它时,请更新为新的来自 next/navigation 的 useRouter。

第 6 步:迁移数据获取方法#

pages 目录使用 getServerSideProps 和 getStaticProps 为页面获取数据。在 app 目录中,这些旧的数据获取函数已被构建于 fetch() 和 async React Server Component 之上的更简单的 API 取代。

app/page.tsx
export default async function Page() {
  // 为此请求选择加入 Next.js 数据缓存。
  // 缓存的响应可以跨请求复用并按需重新验证。
  // 类似于 `getStaticProps`。
  const cachedData = await fetch('https://...', { cache: 'force-cache' })

  // 为此请求选择退出缓存。
  // Next.js 会在每次请求时从数据源获取它。
  // 这是默认的 fetch 行为。
  // 类似于 `getServerSideProps`。
  const uncachedData = await fetch('https://...', { cache: 'no-store' })

  // 缓存此请求,但最多每 10 秒重新验证一次。
  // 类似于带 `revalidate` 选项的 `getStaticProps`。
  const revalidatedData = await fetch('https://...', {
    next: { revalidate: 10 },
  })

  return <div>...</div>
}
app/page.js
export default async function Page() {
  // 为此请求选择加入 Next.js 数据缓存。
  // 缓存的响应可以跨请求复用并按需重新验证。
  // 类似于 `getStaticProps`。
  const cachedData = await fetch('https://...', { cache: 'force-cache' })

  // 为此请求选择退出缓存。
  // Next.js 会在每次请求时从数据源获取它。
  // 这是默认的 fetch 行为。
  // 类似于 `getServerSideProps`。
  const uncachedData = await fetch('https://...', { cache: 'no-store' })

  // 缓存此请求,但最多每 10 秒重新验证一次。
  // 类似于带 `revalidate` 选项的 `getStaticProps`。
  const revalidatedData = await fetch('https://...', {
    next: { revalidate: 10 },
  })

  return <div>...</div>
}

服务端渲染(getServerSideProps)#

在 pages 目录中,getServerSideProps 用于在服务端获取数据,并将 props 转发给文件中默认导出的 React 组件。页面的初始 HTML 由服务端预渲染,随后在浏览器中“水合”(hydrating)页面(使其具有交互性)。

pages/dashboard.js
// `pages` 目录

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 Component 将数据获取并置到 React 组件中。这让我们可以向客户端发送更少的 JavaScript,同时保留来自服务端的渲染 HTML。

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

app/dashboard/page.tsx
// `app` 目录

// 此函数可以任意命名
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>
  )
}
app/dashboard/page.js
// `app` 目录

// 此函数可以任意命名
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` 目录

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 目录暴露了新的只读函数来检索请求数据:

app/page.tsx
// `app` 目录
import { cookies, headers } from 'next/headers'

async function getData() {
  const authHeader = (await headers()).get('authorization')

  return '...'
}

export default async function Page() {
  // 你可以在 Server Component 内部直接使用 `cookies` 或 `headers`
  // 或在你的数据获取函数中使用
  const theme = (await cookies()).get('theme')
  const data = await getData()
  return '...'
}
app/page.js
// `app` 目录
import { cookies, headers } from 'next/headers'

async function getData() {
  const authHeader = (await headers()).get('authorization')

  return '...'
}

export default async function Page() {
  // 你可以在 Server Component 内部直接使用 `cookies` 或 `headers`
  // 或在你的数据获取函数中使用
  const theme = (await cookies()).get('theme')
  const data = await getData()
  return '...'
}

静态站点生成(getStaticProps)#

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

pages/index.js
// `pages` 目录

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` 目录

// 此函数可以任意命名
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` 目录
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 更简单,并且可以在布局内部使用。generateStaticParams 的返回结构是一个段数组,而不是嵌套 param 对象的数组或已解析路径的字符串。

app/posts/[id]/page.js
// `app` 目录
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 取代,这更适合具有多个动态段的嵌套路由。


取代 fallback#

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

pages/posts/[id].js
// `pages` 目录

export async function getStaticPaths() {
  return {
    paths: [],
    fallback: 'blocking'
  };
}

export async function getStaticProps({ params }) {
  ...
}

export default function Post({ post }) {
  return ...
}

在 app 目录中,config.dynamicParams 属性控制如何处理不在 generateStaticParams 中的参数:

  • true:(默认)未包含在 generateStaticParams 中的动态段会按需生成。
  • false:未包含在 generateStaticParams 中的动态段将返回 404。

这取代了 pages 目录中 getStaticPaths 的 fallback: true | false | 'blocking' 选项。fallback: 'blocking' 选项未包含在 dynamicParams 中,因为在流式渲染下 'blocking' 与 true 之间的差异可以忽略不计。

app/posts/[id]/page.js
// `app` 目录

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(默认值)的情况下,当请求一个尚未生成的路由段时,它会被服务端渲染并缓存。

增量静态再生(带 revalidate 的 getStaticProps)#

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

pages/index.js
// `pages` 目录

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` 目录

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 Route#

API Route 在 pages/api 目录中继续正常工作,无需任何更改。不过,它们已被 app 目录中的 Route Handler 取代。

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

app/api/route.ts
export async function GET(request: Request) {}
app/api/route.js
export async function GET(request) {}

小知识:如果你之前使用 API Route 从客户端调用外部 API,现在可以改用 Server Component 来安全地获取数据。了解更多关于数据获取的信息。

单页应用#

如果你同时也从单页应用(SPA)迁移到 Next.js,请参阅我们的文档以了解更多信息。

第 7 步:样式设置#

在 pages 目录中,全局样式表仅限于 pages/_app.js。有了 app 目录,这一限制被取消。全局样式可以添加到任何布局、页面或组件中。

Tailwind CSS#

如果你使用 Tailwind CSS,则需要将 app 目录添加到 tailwind.config.js 文件中:

tailwind.config.js
module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}', // <-- 添加此行
    './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 router 提供服务的路由之间导航时,会进行硬导航。使用 next/link 的自动链接预取不会跨 router 预取。

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

Codemod#

当某个功能被弃用时,Next.js 提供 Codemod 转换来帮助你升级代码库。有关更多信息,请参阅 Codemod。

Next.js 中文网