NNext.js 中文网 GitHub

如何从 Create React App 迁移到 Next.js

了解如何将现有的 React 应用程序从 Create React App 迁移到 Next.js。

本指南将帮助你将现有的 Create React App (CRA) 站点迁移到 Next.js。

为什么要切换?#

你可能想要从 Create React App 切换到 Next.js 的原因有以下几点:

初始页面加载时间慢#

Create React App 使用纯粹的客户端渲染。纯客户端应用程序,也称为单页应用程序(SPA),通常初始页面加载时间较慢。这主要有以下几个原因:

  1. 浏览器需要等待 React 代码和整个应用程序包下载并运行,你的代码才能发送请求来加载数据。
  2. 随着你添加的每个新功能和依赖项,你的应用程序代码都会增长。

没有自动代码分割#

前面提到的加载时间慢的问题可以通过代码分割在一定程度上缓解。但是,如果你尝试手动进行代码分割,可能会无意中引入网络瀑布流。Next.js 在其路由器和构建流程中内置了自动代码分割和 tree-shaking。

网络瀑布流#

性能不佳的一个常见原因是应用程序发出连续的客户端-服务器请求来获取数据。在 SPA 中,一种数据获取模式是先渲染占位符,然后在组件挂载后再获取数据。遗憾的是,子组件只有在其父组件完成自身数据加载后才能开始获取数据,从而导致请求的“瀑布流”。

虽然 Next.js 支持客户端数据获取,但它也允许你将数据获取移到服务器端。这通常可以完全消除客户端-服务器之间的瀑布流。

快速且有意为之的加载状态#

借助对通过 React Suspense 进行流式渲染的内置支持,你可以定义 UI 的哪些部分先加载以及加载顺序,而不会产生网络瀑布流。

这使你能够构建加载更快的页面,并消除布局偏移。

选择数据获取策略#

根据你的需求,Next.js 允许你在页面或组件级别选择数据获取策略。例如,你可以从 CMS 获取数据并在构建时渲染博客文章(SSG)以获得快速加载速度,或者在必要时在请求时获取数据(SSR)。

Proxy#

Next.js Proxy 允许你在请求完成之前在服务器上运行代码。例如,对于仅限已认证用户访问的页面,你可以在 proxy 中将用户重定向到登录页面,从而避免闪烁出未经认证的内容。你还可以将它用于 A/B 测试、实验和国际化等功能。

内置优化#

图片(Images)、字体(fonts)和第三方脚本通常对应用程序的性能有很大影响。Next.js 包含专门的组件和 API,可自动为你优化它们。

迁移步骤#

我们的目标是尽快让 Next.js 应用程序运行起来,以便你随后逐步采用 Next.js 的功能。首先,我们会将你的应用程序视为纯客户端应用程序(SPA),而不立即替换你现有的路由器。这可以降低复杂性和合并冲突。

注意:如果你使用了高级 CRA 配置,例如 package.json 中自定义的 homepage 字段、自定义的 service worker,或特定的 Babel/webpack 调整,请参阅本指南末尾的其他注意事项部分,了解如何在 Next.js 中复制或适配这些功能。

第 1 步:安装 Next.js 依赖项#

在现有项目中安装 Next.js:

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

第 2 步:创建 Next.js 配置文件#

在项目根目录(与 package.json 同级)创建一个 next.config.ts。该文件用于存放你的 Next.js 配置选项。

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  output: 'export', // 输出单页应用程序(SPA)
  distDir: 'build', // 将构建输出目录更改为 `build`
}

export default nextConfig

注意:使用 output: 'export' 意味着你正在进行静态导出。你将无法使用 SSR 或 API 等服务器端功能。你可以删除这一行以利用 Next.js 的服务器端功能。

第 3 步:创建根布局#

Next.js App Router 应用程序必须包含一个根布局文件,它是一个 React Server Component,将包裹你的所有页面。

在 CRA 应用程序中,与根布局文件最接近的等价物是 public/index.html,它包含你的 <html>、<head> 和 <body> 标签。

  1. 在 src 文件夹中创建一个新的 app 目录(如果你希望 app 位于根目录,也可以在项目根目录创建)。
  2. 在 app 目录中创建一个 layout.tsx(或 layout.js)文件:
app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return '...'
}
app/layout.js
export default function RootLayout({ children }) {
  return '...'
}

现在将旧 index.html 的内容复制到这个 <RootLayout> 组件中。将 body div#root(以及 body noscript)替换为 <div id="root">{children}</div>。

app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head>
        <meta charSet="UTF-8" />
        <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>React App</title>
        <meta name="description" content="Web site created..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}
app/layout.js
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>React App</title>
        <meta name="description" content="Web site created..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

小知识:Next.js 默认会忽略 CRA 的 public/manifest.json、额外的图标以及测试配置。如果你需要这些,Next.js 通过其 Metadata API 和测试设置提供支持。

第 4 步:元数据#

Next.js 会自动包含 <meta charset="UTF-8" /> 和 <meta name="viewport" content="width=device-width, initial-scale=1" /> 标签,因此你可以将它们从 <head> 中移除:

app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head>
        <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
        <title>React App</title>
        <meta name="description" content="Web site created..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}
app/layout.js
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
        <title>React App</title>
        <meta name="description" content="Web site created..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

任何元数据文件,例如 favicon.ico、icon.png、robots.txt,只要将它们放在 app 目录的顶层,就会自动添加到应用程序的 <head> 标签中。在将所有支持的文件移动到 app 目录后,你可以放心地删除它们的 <link> 标签:

app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head>
        <title>React App</title>
        <meta name="description" content="Web site created..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}
app/layout.js
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <title>React App</title>
        <meta name="description" content="Web site created..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

最后,Next.js 可以使用 Metadata API 管理你剩余的 <head> 标签。将你最后的元数据信息移到一个导出的 metadata 对象中:

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

export const metadata: Metadata = {
  title: 'React App',
  description: 'Web site created with Next.js.',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}
app/layout.js
export const metadata = {
  title: 'React App',
  description: 'Web site created with Next.js.',
}

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

通过上述更改,你已经从在 index.html 中声明所有内容转变为使用框架内置的 Next.js 基于约定的方法(Metadata API)。这种方法使你能够更轻松地改善 SEO 和页面的网络可分享性。

第 5 步:样式#

与 CRA 一样,Next.js 开箱即支持 CSS Modules。它还支持全局 CSS 导入。

如果你有一个全局 CSS 文件,请将其导入到 app/layout.tsx 中:

app/layout.tsx
import '../index.css'

export const metadata = {
  title: 'React App',
  description: 'Web site created with Next.js.',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

如果你使用的是 Tailwind CSS,请参阅我们的安装文档。

第 6 步:创建入口页面#

Create React App 使用 src/index.tsx(或 index.js)作为入口点。在 Next.js(App Router)中,app 目录中的每个文件夹都对应一个路由,每个文件夹都应该有一个 page.tsx。

由于我们目前希望将应用保持为 SPA 并拦截所有路由,我们将使用可选的全捕获路由。

  1. 在 app 中创建一个 [[...slug]] 目录。
bash
app
 ┣ [[...slug]]
 ┃ ┗ page.tsx
 ┣ layout.tsx
  1. 将以下内容添加到 page.tsx:
app/[[...slug]]/page.tsx
export function generateStaticParams() {
  return [{ slug: [''] }]
}

export default function Page() {
  return '...' // 稍后我们会更新这里
}
app/[[...slug]]/page.js
export function generateStaticParams() {
  return [{ slug: [''] }]
}

export default function Page() {
  return '...' // 稍后我们会更新这里
}

这告诉 Next.js 为空 slug (/) 生成一个路由,实际上是将所有路由映射到同一个页面。这个页面是一个 Server Component,会被预渲染为静态 HTML。

第 7 步:添加纯客户端入口#

接下来,我们会将你 CRA 的根 App 组件嵌入到一个 Client Component 中,以便所有逻辑都保留在客户端。如果你第一次使用 Next.js,值得注意的是 Client Components(默认情况下)仍然会在服务器端预渲染。你可以将它们理解为额外具备运行客户端 JavaScript 的能力。

在 app/[[...slug]]/ 中创建一个 client.tsx(或 client.js):

app/[[...slug]]/client.tsx
'use client'

import dynamic from 'next/dynamic'

const App = dynamic(() => import('../../App'), { ssr: false })

export function ClientOnly() {
  return <App />
}
app/[[...slug]]/client.js
'use client'

import dynamic from 'next/dynamic'

const App = dynamic(() => import('../../App'), { ssr: false })

export function ClientOnly() {
  return <App />
}
  • 'use client' 指令使该文件成为一个 Client Component。
  • 带有 ssr: false 的 dynamic 导入会禁用 <App /> 组件的服务器端渲染,使其成为真正的纯客户端(SPA)。

现在更新你的 page.tsx(或 page.js)以使用你的新组件:

app/[[...slug]]/page.tsx
import { ClientOnly } from './client'

export function generateStaticParams() {
  return [{ slug: [''] }]
}

export default function Page() {
  return <ClientOnly />
}
app/[[...slug]]/page.js
import { ClientOnly } from './client'

export function generateStaticParams() {
  return [{ slug: [''] }]
}

export default function Page() {
  return <ClientOnly />
}

第 8 步:更新静态图片导入#

在 CRA 中,导入图片文件会以字符串形式返回其公共 URL:

tsx
import image from './img.png'

export default function App() {
  return <img src={image} />
}

在 Next.js 中,静态图片导入会返回一个对象。然后可以将该对象直接与 Next.js 的 <Image> 组件一起使用,或者你可以将对象的 src 属性与你现有的 <img> 标签一起使用。

<Image> 组件具有自动图片优化的额外好处。<Image> 组件会根据图片尺寸自动设置生成的 <img> 的 width 和 height 属性。这可以防止图片加载时发生布局偏移。但是,如果你的应用中包含的图片只设置了其中一个维度的样式,而另一个维度未设置为 auto,则可能会出现问题。当未设置为 auto 时,该维度将默认为 <img> 尺寸属性的值,这可能导致图片看起来变形。

保留 <img> 标签可以减少应用程序中的改动量,并避免上述问题。之后你可以选择迁移到 <Image> 组件,通过配置 loader来利用图片优化,或者迁移到具有自动图片优化功能的默认 Next.js 服务器。

将从 /public 导入的图片的绝对导入路径转换为相对导入:

tsx
// 之前
import logo from '/logo.png'

// 之后
import logo from '../public/logo.png'

将图片的 src 属性而不是整个图片对象传递给你的 <img> 标签:

tsx
// 之前
<img src={logo} />

// 之后
<img src={logo.src} />

或者,你可以根据文件名引用图片资源的公共 URL。例如,public/logo.png 将为你的应用程序在 /logo.png 处提供该图片,这就是 src 值。

警告: 如果你使用的是 TypeScript,在访问 src 属性时可能会遇到类型错误。要修复这些错误,你需要将 next-env.d.ts 添加到 tsconfig.json 文件的 include 数组中。当你在第 9 步运行应用程序时,Next.js 会自动生成此文件。

第 9 步:迁移环境变量#

Next.js 对环境变量的支持与 CRA 类似,但对于任何你想在浏览器中暴露的变量,都必须使用 NEXT_PUBLIC_ 前缀。

主要区别在于用于在客户端暴露环境变量的前缀。将所有带有 REACT_APP_ 前缀的环境变量更改为 NEXT_PUBLIC_。

第 10 步:更新 package.json 中的脚本#

更新 package.json 中的脚本以使用 Next.js 命令。此外,将 .next 和 next-env.d.ts 添加到你的 .gitignore 中:

package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "npx serve@latest ./build"
  }
}
.gitignore
# ...
.next
next-env.d.ts

现在你可以运行:

bash · pnpm
pnpm dev
bash · npm
npm run dev
bash · yarn
yarn dev
bash · bun
bun dev

打开 http://localhost:3000。你应该会看到你的应用程序现在运行在 Next.js 上(以 SPA 模式)。

第 11 步:清理#

现在你可以删除特定于 Create React App 的产物:

  • public/index.html
  • src/index.tsx
  • src/react-app-env.d.ts
  • reportWebVitals 设置
  • react-scripts 依赖项(从 package.json 中卸载它)

其他注意事项#

在 CRA 中使用自定义 homepage#

如果你在 CRA 的 package.json 中使用 homepage 字段来在特定子路径下提供应用,你可以在 Next.js 中使用 next.config.ts 里的 basePath 配置来实现相同的效果:

next.config.ts
import { NextConfig } from 'next'

const nextConfig: NextConfig = {
  basePath: '/my-subpath',
  // ...
}

export default nextConfig

处理自定义 Service Worker#

如果你使用了 CRA 的 service worker(例如来自 create-react-app 的 serviceWorker.js),你可以使用以下语法注册这个 service worker:

ts
await navigator.serviceWorker.register(new URL('../serviceWorker.js', import.meta.url), ...)

了解更多关于如何使用 Next.js 创建渐进式 Web 应用程序(PWA)的信息。

代理 API 请求#

如果你的 CRA 应用使用 package.json 中的 proxy 字段将请求转发到后端服务器,你可以在 next.config.ts 中使用 Next.js rewrites来实现相同的效果:

next.config.ts
import { NextConfig } from 'next'

const nextConfig: NextConfig = {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: 'https://your-backend.com/:path*',
      },
    ]
  },
}

自定义 Webpack#

如果你在 CRA 中有自定义的 webpack 或 Babel 配置,你可以在 next.config.ts 中扩展 Next.js 的配置:

next.config.ts
import { NextConfig } from 'next'

const nextConfig: NextConfig = {
  webpack: (config, { isServer }) => {
    // 在此处修改 webpack 配置
    return config
  },
}

export default nextConfig

注意:这将需要通过在 dev 脚本中添加 --webpack 来使用 Webpack。

TypeScript 设置#

如果你有 tsconfig.json,Next.js 会自动设置 TypeScript。请确保 next-env.d.ts 列在你的 tsconfig.json 的 include 数组中:

json
{
  "include": ["next-env.d.ts", "app/**/*", "src/**/*"]
}

打包器兼容性#

Create React App 使用 webpack 进行打包。Next.js 现在默认使用 Turbopack 以实现更快的本地开发:

bash
next dev  # 默认使用 Turbopack

要改用 Webpack(类似于 CRA):

bash
next dev --webpack

如果你需要从 CRA 迁移高级 webpack 设置,仍然可以提供自定义 webpack 配置。

下一步#

如果一切顺利,你现在拥有了一个作为单页应用程序运行的正常工作的 Next.js 应用程序。你还没有利用 Next.js 的服务器端渲染或基于文件的路由等功能,但现在可以逐步采用它们:

注意:使用静态导出(output: 'export')目前不支持 useParams hook 或其他服务器端功能。要使用所有 Next.js 功能,请从 next.config.ts 中移除 output: 'export'。

Next.js 中文网