如何从 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),通常初始页面加载时间较慢。这主要有以下几个原因:
- 浏览器需要等待 React 代码和整个应用程序包下载并运行,你的代码才能发送请求来加载数据。
- 随着你添加的每个新功能和依赖项,你的应用程序代码都会增长。
没有自动代码分割#
前面提到的加载时间慢的问题可以通过代码分割在一定程度上缓解。但是,如果你尝试手动进行代码分割,可能会无意中引入网络瀑布流。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:
pnpm add next@latestnpm install next@latestyarn add next@latestbun add next@latest第 2 步:创建 Next.js 配置文件#
在项目根目录(与 package.json 同级)创建一个 next.config.ts。该文件用于存放你的 Next.js 配置选项。
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> 标签。
- 在
src文件夹中创建一个新的app目录(如果你希望app位于根目录,也可以在项目根目录创建)。 - 在
app目录中创建一个layout.tsx(或layout.js)文件:
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return '...'
}export default function RootLayout({ children }) {
return '...'
}现在将旧 index.html 的内容复制到这个 <RootLayout> 组件中。将 body div#root(以及 body noscript)替换为 <div id="root">{children}</div>。
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>
)
}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> 中移除:
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>
)
}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> 标签:
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>
)
}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 对象中:
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>
)
}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 中:
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 并拦截所有路由,我们将使用可选的全捕获路由。
- 在
app中创建一个[[...slug]]目录。
app
┣ [[...slug]]
┃ ┗ page.tsx
┣ layout.tsx- 将以下内容添加到
page.tsx:
export function generateStaticParams() {
return [{ slug: [''] }]
}
export default function Page() {
return '...' // 稍后我们会更新这里
}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):
'use client'
import dynamic from 'next/dynamic'
const App = dynamic(() => import('../../App'), { ssr: false })
export function ClientOnly() {
return <App />
}'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)以使用你的新组件:
import { ClientOnly } from './client'
export function generateStaticParams() {
return [{ slug: [''] }]
}
export default function Page() {
return <ClientOnly />
}import { ClientOnly } from './client'
export function generateStaticParams() {
return [{ slug: [''] }]
}
export default function Page() {
return <ClientOnly />
}第 8 步:更新静态图片导入#
在 CRA 中,导入图片文件会以字符串形式返回其公共 URL:
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 导入的图片的绝对导入路径转换为相对导入:
// 之前
import logo from '/logo.png'
// 之后
import logo from '../public/logo.png'将图片的 src 属性而不是整个图片对象传递给你的 <img> 标签:
// 之前
<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 中:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "npx serve@latest ./build"
}
}# ...
.next
next-env.d.ts现在你可以运行:
pnpm devnpm run devyarn devbun dev打开 http://localhost:3000。你应该会看到你的应用程序现在运行在 Next.js 上(以 SPA 模式)。
第 11 步:清理#
现在你可以删除特定于 Create React App 的产物:
public/index.htmlsrc/index.tsxsrc/react-app-env.d.tsreportWebVitals设置react-scripts依赖项(从package.json中卸载它)
其他注意事项#
在 CRA 中使用自定义 homepage#
如果你在 CRA 的 package.json 中使用 homepage 字段来在特定子路径下提供应用,你可以在 Next.js 中使用 next.config.ts 里的 basePath 配置来实现相同的效果:
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:
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来实现相同的效果:
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 的配置:
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 数组中:
{
"include": ["next-env.d.ts", "app/**/*", "src/**/*"]
}打包器兼容性#
Create React App 使用 webpack 进行打包。Next.js 现在默认使用 Turbopack 以实现更快的本地开发:
next dev # 默认使用 Turbopack要改用 Webpack(类似于 CRA):
next dev --webpack如果你需要从 CRA 迁移高级 webpack 设置,仍然可以提供自定义 webpack 配置。
下一步#
如果一切顺利,你现在拥有了一个作为单页应用程序运行的正常工作的 Next.js 应用程序。你还没有利用 Next.js 的服务器端渲染或基于文件的路由等功能,但现在可以逐步采用它们:
- 从 React Router 迁移到 Next.js App Router,以获得:
- 使用
<Image>组件优化图片 - 使用
next/font优化字体 - 使用
<Script>组件优化第三方脚本 - 使用 Next.js 推荐规则启用 ESLint
注意:使用静态导出(
output: 'export')目前不支持useParamshook 或其他服务器端功能。要使用所有 Next.js 功能,请从next.config.ts中移除output: 'export'。