从 CRA 迁移

¥Migrating from CRA

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

¥This guide will help you migrate an existing Create React App (CRA) site to Next.js.

为什么要切换？

¥Why Switch?

你可能想要从 Create React App 切换到 Next.js 有几个原因：

¥There are several reasons why you might want to switch from Create React App to Next.js:

初始页面加载时间慢

¥Slow initial page loading time

Create React App 使用纯粹的客户端 React。仅限客户端的应用（也称为单页应用 (SPA)）通常会遇到初始页面加载时间缓慢的问题。发生这种情况有以下几个原因：

¥Create React App uses purely client-side React. Client-side only applications, also known as single-page applications (SPAs), often experience slow initial page loading time. This happens due to a couple of reasons:

浏览器需要等待 React 代码和整个应用包下载并运行，然后代码才能发送加载数据的请求。
¥The browser needs to wait for the React code and your entire application bundle to download and run before your code is able to send requests to load data.
你的应用代码随着你添加的每个新功能和依赖而增长。
¥Your application code grows with every new feature and dependency you add.

没有自动代码分割

¥No automatic code splitting

通过代码拆分可以在一定程度上缓解先前的加载时间缓慢问题。但是，如果你尝试手动进行代码拆分，则可能会无意中引入网络瀑布。Next.js 在其路由和构建管道中内置了自动代码拆分和树摇功能。

¥The previous issue of slow loading times can be somewhat mitigated with code splitting. However, if you try to do code splitting manually, you can inadvertently introduce network waterfalls. Next.js provides automatic code splitting and tree-shaking built into its router and build pipeline.

网络瀑布

¥Network waterfalls

当应用发出连续的客户端-服务器请求来获取数据时，会出现性能不佳的常见原因。SPA 中的数据获取模式之一是渲染占位符，然后在组件安装后获取数据。不幸的是，子组件只能在其父组件完成自身数据加载后才开始获取数据，从而导致请求“瀑布式”增长。

¥A common cause of poor performance occurs when applications make sequential client-server requests to fetch data. One pattern for data fetching in a SPA is to render a placeholder, and then fetch data after the component has mounted. Unfortunately, a child component can only begin fetching data after its parent has finished loading its own data, resulting in a “waterfall” of requests.

虽然 Next.js 支持客户端数据提取，但 Next.js 还允许你将数据提取移动到服务器。这通常会完全消除客户端-服务器瀑布。

¥While client-side data fetching is supported in Next.js, Next.js also lets you move data fetching to the server. This often eliminates client-server waterfalls altogether.

快速且有意的加载状态

¥Fast and intentional loading states

通过内置对通过 React Suspense 进行流式传输的支持，你可以定义 UI 的哪些部分首先加载以及按什么顺序加载，而不会创建网络瀑布。

¥With built-in support for streaming through React Suspense, you can define which parts of your UI load first and in what order, without creating network waterfalls.

这使你能够构建加载速度更快的页面并消除布局变化。

¥This enables you to build pages that are faster to load and eliminate layout shifts.

选择数据获取策略

¥Choose the data fetching strategy

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

¥Depending on your needs, Next.js allows you to choose your data fetching strategy on a page or component-level basis. For example, you could fetch data from your CMS and render blog posts at build time (SSG) for quick load speeds, or fetch data at request time (SSR) when necessary.

中间件

¥Middleware

Next.js 中间件允许你在请求完成之前在服务器上运行代码。例如，你可以通过将用户重定向到中间件中仅经过身份验证的页面的登录页面来避免未经身份验证的内容闪现。你还可以将其用于 A/B 测试、实验和 internationalization 等功能。

¥Next.js Middleware allows you to run code on the server before a request is completed. For instance, you can avoid a flash of unauthenticated content by redirecting a user to a login page in the middleware for authenticated-only pages. You can also use it for features like A/B testing, experimentation, and internationalization.

内置优化

¥Built-in Optimizations

图片、fonts 和第三方脚本通常会对应用的性能产生很大影响。Next.js 包含专门的组件和 API，可自动为你优化它们。

¥Images, fonts, and third-party scripts often have a large impact on an application’s performance. Next.js includes specialized components and APIs that automatically optimize them for you.

迁移步骤

¥Migration Steps

我们的目标是尽快获得一个可以运行的 Next.js 应用，以便你可以逐步采用 Next.js 功能。首先，我们将你的应用视为纯客户端应用 (SPA)，而不会立即替换你现有的路由。这降低了复杂性和合并冲突。

¥Our goal is to get a working Next.js application as quickly as possible so that you can then adopt Next.js features incrementally. To begin with, we’ll treat your application as a purely client-side application (SPA) without immediately replacing your existing router. This reduces complexity and merge conflicts.

注意：如果你正在使用高级 CRA 配置，例如 package.json 中的自定义 homepage 字段、自定义服务工作者或特定的 Babel/webpack 调整，请参阅本指南末尾的其他注意事项部分，获取有关在 Next.js 中复制或调整这些功能的提示。
¥Note: If you are using advanced CRA configurations such as a custom homepage field in your package.json, a custom service worker, or specific Babel/webpack tweaks, please see the Additional Considerations section at the end of this guide for tips on replicating or adapting these features in Next.js.

步骤 1：安装 Next.js 依赖

¥Step 1: Install the Next.js Dependency

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

¥Install Next.js in your existing project:

bash

npm install next@latest

步骤 2：创建 Next.js 配置文件

¥Step 2: Create the Next.js Configuration File

在项目根目录下创建 next.config.ts（与 package.json 同级）。此文件包含你的 Next.js 配置选项。

¥Create a next.config.ts at the root of your project (same level as your package.json). This file holds your Next.js configuration options.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  output: 'export', // Outputs a Single-Page Application (SPA)
  distDir: 'build', // Changes the build output directory to `build`
}

export default nextConfig

注意：使用 output: 'export' 意味着你正在执行静态导出。你将无法访问服务器端功能，如 SSR 或 API。你可以删除此行以利用 Next.js 服务器功能。
¥Note: Using output: 'export' means you’re doing a static export. You will not have access to server-side features like SSR or APIs. You can remove this line to leverage Next.js server features.

步骤 3：创建根布局

¥Step 3: Create the Root Layout

Next.js 应用路由应用必须包含根布局文件，这是一个将封装所有页面的 React 服务器组件。

¥A Next.js App Router application must include a root layout file, which is a React Server Component that will wrap all your pages.

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

¥The closest equivalent of the root layout file in a CRA application is public/index.html, which includes your <html>, <head>, and <body> tags.

在 src 目录中创建一个新的 app 目录（或者，如果你希望在根目录中使用 app，则在项目根目录中创建一个新的 app 目录）。
¥Create a new app directory inside your src directory (or at your project root if you prefer app at the root).
在 app 目录中，创建一个 layout.tsx（或 layout.js）文件：
¥Inside the app directory, create a layout.tsx (or layout.js) file:

tsx

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

jsx

export default function RootLayout({ children }) {
  return '...'
}

现在将旧 index.html 的内容复制到此 <RootLayout> 组件中。用 <div id="root">{children}</div> 替换 body div#root（和 body noscript）。

¥Now copy the content of your old index.html into this <RootLayout> component. Replace body div#root (and body noscript) with <div id="root">{children}</div>.

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>
  )
}

jsx

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 在其元数据 API 和测试设置中提供支持。
¥Good to know: Next.js ignores CRA’s public/manifest.json, additional iconography, and testing configuration by default. If you need these, Next.js has support with its Metadata API and Testing setup.

步骤 4：元数据

¥Step 4: Metadata

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

¥Next.js automatically includes the <meta charset="UTF-8" /> and <meta name="viewport" content="width=device-width, initial-scale=1" /> tags, so you can remove them from <head>:

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>
  )
}

jsx

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> 标签：

¥Any metadata files such as favicon.ico, icon.png, robots.txt are automatically added to the application <head> tag as long as you have them placed into the top level of the app directory. After moving all supported files into the app directory you can safely delete their <link> tags:

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>
  )
}

jsx

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 可以使用元数据 API 管理你最后的 <head> 标签。将最终元数据信息移至导出的 metadata 对象中：

¥Finally, Next.js can manage your last <head> tags with the Metadata API. Move your final metadata info into an exported metadata object:

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>
  )
}

jsx

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 中声明所有内容转变为使用框架 (元数据 API) 中内置的 Next.js 基于约定的方法。这种方法使你能够更轻松地提高页面的 SEO 和网络共享性。

¥With the above changes, you shifted from declaring everything in your index.html to using Next.js' convention-based approach built into the framework (Metadata API). This approach enables you to more easily improve your SEO and web shareability of your pages.

步骤 5：样式

¥Step 5: Styles

与 CRA 一样，Next.js 开箱即用地支持 CSS 模块。它还支持全局 CSS 导入。

¥Like CRA, Next.js supports CSS Modules out of the box. It also supports global CSS imports.

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

¥If you have a global CSS file, import it into your app/layout.tsx:

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，请参阅我们的安装文档。

¥If you’re using Tailwind CSS, see our installation docs.

步骤 6：创建入口点页面

¥Step 6: Create the Entrypoint Page

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

¥Create React App uses src/index.tsx (or index.js) as the entry point. In Next.js (App Router), each folder inside the app directory corresponds to a route, and each folder should have a page.tsx.

由于我们暂时希望将应用保留为 SPA 并拦截所有路由，因此我们将使用可选的包罗万象的路由。

¥Since we want to keep the app as an SPA for now and intercept all routes, we’ll use an optional catch-all route.

在 app 内创建 [[...slug]] 目录。
¥Create a [[...slug]] directory inside app.

bash

app
 ┣ [[...slug]]
 ┃ ┗ page.tsx
 ┣ layout.tsx

将以下内容添加到 page.tsx：
¥Add the following to page.tsx:

tsx

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

export default function Page() {
  return '...' // We'll update this
}

jsx

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

export default function Page() {
  return '...' // We'll update this
}

这告诉 Next.js 为空 slug (/) 生成单个路由，从而有效地将所有路由映射到同一页面。此页面是服务器组件，预渲染为静态 HTML。

¥This tells Next.js to generate a single route for the empty slug (/), effectively mapping all routes to the same page. This page is a Server Component, prerendered into static HTML.

步骤 7：添加仅客户端入口点

¥Step 7: Add a Client-Only Entrypoint

接下来，我们将你的 CRA 的根 App 组件嵌入到客户端组件中，以便所有逻辑都保留在客户端。如果这是你第一次使用 Next.js，那么值得了解的是，客户端组件（默认情况下）仍在服务器上预渲染。你可以将它们视为具有运行客户端 JavaScript 的附加功能。

¥Next, we’ll embed your CRA’s root App component inside a Client Component so that all logic remains client-side. If this is your first time using Next.js, it's worth knowing that clients components (by default) are still prerendered on the server. You can think about them as having the additional capability of running client-side JavaScript.

在 app/[[...slug]]/ 中创建 client.tsx（或 client.js）：

¥Create a client.tsx (or client.js) in app/[[...slug]]/:

tsx

'use client'

import dynamic from 'next/dynamic'

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

export function ClientOnly() {
  return <App />
}

jsx

'use client'

import dynamic from 'next/dynamic'

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

export function ClientOnly() {
  return <App />
}

'use client' 指令使此文件成为客户端组件。
¥The 'use client' directive makes this file a Client Component.
dynamic 与 ssr: false 的导入禁用了 <App /> 组件的服务器端渲染，使其成为真正的客户端专用 (SPA)。
¥The dynamic import with ssr: false disables server-side rendering for the <App /> component, making it truly client-only (SPA).

现在更新你的 page.tsx（或 page.js）以使用你的新组件：

¥Now update your page.tsx (or page.js) to use your new component:

tsx

import { ClientOnly } from './client'

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

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

jsx

import { ClientOnly } from './client'

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

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

步骤 8：更新静态图片导入

¥Step 8: Update Static Image Imports

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

¥In CRA, importing an image file returns its public URL as a string:

tsx

import image from './img.png'

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

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

¥With Next.js, static image imports return an object. The object can then be used directly with the Next.js <Image> component, or you can use the object's src property with your existing <img> tag.

<Image> 组件具有自动图片优化的额外优势。<Image> 组件根据图片的尺寸自动设置生成的 <img> 的 width 和 height 属性。这可以防止图片加载时布局发生变化。但是，如果你的应用包含的图片只有一个尺寸被设置样式而另一个尺寸没有被设置成 auto，则这可能会导致问题。当未将样式设置为 auto 时，尺寸将默认为 <img> 尺寸属性的值，这可能会导致图片出现扭曲。

¥The <Image> component has the added benefits of automatic image optimization. The <Image> component automatically sets the width and height attributes of the resulting <img> based on the image's dimensions. This prevents layout shifts when the image loads. However, this can cause issues if your app contains images with only one of their dimensions being styled without the other styled to auto. When not styled to auto, the dimension will default to the <img> dimension attribute's value, which can cause the image to appear distorted.

保留 <img> 标签将减少应用中的更改量并防止上述问题。然后，你可以选择稍后迁移到 <Image> 组件以利用配置加载器优化图片，或者移动到具有自动图片优化功能的默认 Next.js 服务器。

¥Keeping the <img> tag will reduce the amount of changes in your application and prevent the above issues. You can then optionally later migrate to the <Image> component to take advantage of optimizing images by configuring a loader, or moving to the default Next.js server which has automatic image optimization.

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

¥Convert absolute import paths for images imported from /public into relative imports:

tsx

// Before
import logo from '/logo.png'

// After
import logo from '../public/logo.png'

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

¥Pass the image src property instead of the whole image object to your <img> tag:

tsx

// Before
<img src={logo} />

// After
<img src={logo.src} />

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

¥Alternatively, you can reference the public URL for the image asset based on the filename. For example, public/logo.png will serve the image at /logo.png for your application, which would be the src value.

警告：如果你使用的是 TypeScript，则在访问 src 属性时可能会遇到类型错误。要修复它们，你需要将 next-env.d.ts 添加到 tsconfig.json 文件的 include 数组中。当你在步骤 9 运行应用时，Next.js 将自动生成此文件。
¥Warning: If you're using TypeScript, you might encounter type errors when accessing the src property. To fix them, you need to add next-env.d.ts to the include array of your tsconfig.json file. Next.js will automatically generate this file when you run your application on step 9.

步骤 9：迁移环境变量

¥Step 9: Migrate Environment Variables

Next.js 支持与 CRA 类似的环境变量，但要求你想要在浏览器中公开的任何变量都带有 NEXT_PUBLIC_ 前缀。

¥Next.js supports environment variables similarly to CRA but requires a NEXT_PUBLIC_ prefix for any variable you want to expose in the browser.

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

¥The main difference is the prefix used to expose environment variables on the client-side. Change all environment variables with the REACT_APP_ prefix to NEXT_PUBLIC_.

步骤 10：更新 `package.json` 中的脚本

¥Step 10: Update Scripts in package.json

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

¥Update your package.json scripts to use Next.js commands. Also, add .next and next-env.d.ts to your .gitignore:

json

{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build",
    "start": "npx serve@latest ./build"
  }
}

txt

# ...
.next
next-env.d.ts

现在你可以运行：

¥Now you can run:

bash

npm run dev

打开 http://localhost:3000。你应该看到你的应用现在在 Next.js 上运行（在 SPA 模式下）。

¥Open http://localhost:3000. You should see your application now running on Next.js (in SPA mode).

步骤 11：清理

¥Step 11: Clean Up

你现在可以删除特定于 Create React App 的工件：

¥You can now remove artifacts that are specific to Create React App:

public/index.html
src/index.tsx
src/react-app-env.d.ts
reportWebVitals 设置
¥The reportWebVitals setup
react-scripts 依赖（从 package.json 中卸载）
¥The react-scripts dependency (uninstall it from package.json)

其他注意事项

¥Additional Considerations

在 CRA 中使用自定义 `homepage`

¥Using a Custom homepage in CRA

如果你使用 CRA package.json 中的 homepage 字段在特定子路径下为应用提供服务，则可以使用 next.config.ts 中的 basePath 配置在 Next.js 中复制该字段：

¥If you used the homepage field in your CRA package.json to serve the app under a specific subpath, you can replicate that in Next.js using the basePath configuration in next.config.ts:

import { NextConfig } from 'next'

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

export default nextConfig

处理自定义 `Service Worker`

¥Handling a Custom Service Worker

如果你使用了 CRA 的服务工作线程（例如，create-react-app 中的 serviceWorker.js），你可以了解如何使用 Next.js 创建渐进式 Web 应用 (PWA)。

¥If you used CRA’s service worker (e.g., serviceWorker.js from create-react-app), you can learn how to create Progressive Web Applications (PWAs) with Next.js.

代理 API 请求

¥Proxying API Requests

如果你的 CRA 应用使用 package.json 中的 proxy 字段将请求转发到后端服务器，你可以在 next.config.ts 中使用 Next.js 重写复制此操作：

¥If your CRA app used the proxy field in package.json to forward requests to a backend server, you can replicate this with Next.js rewrites in next.config.ts:

import { NextConfig } from 'next'

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

自定义 Webpack / Babel 配置

¥Custom Webpack / Babel Config

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

¥If you had a custom webpack or Babel configuration in CRA, you can extend Next.js’s config in next.config.ts:

import { NextConfig } from 'next'

const nextConfig: NextConfig = {
  webpack: (config, { isServer }) => {
    // Modify the webpack config here
    return config
  },
}

export default nextConfig

注意：这将需要通过从 dev 脚本中删除 --turbopack 来禁用 Turbopack。
¥Note: This will require disabling Turbopack by removing --turbopack from your dev script.

TypeScript 设置

¥TypeScript Setup

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

¥Next.js automatically sets up TypeScript if you have a tsconfig.json. Make sure next-env.d.ts is listed in your tsconfig.json include array:

json

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

打包器兼容性

¥Bundler Compatibility

Create React App 和 Next.js 都默认使用 webpack 进行打包。Next.js 还提供 Turbopack 以实现更快的本地开发：

¥Both Create React App and Next.js default to webpack for bundling. Next.js also offers Turbopack for faster local development with:

bash

next dev --turbopack

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

¥You can still provide a custom webpack configuration if you need to migrate advanced webpack settings from CRA.

下一步

¥Next Steps

如果一切正常，你现在有一个可以正常运行的 Next.js 应用作为单页应用运行。你尚未利用 Next.js 功能（如服务器端渲染或基于文件的路由），但现在你可以逐步实现这些功能：

¥If everything worked, you now have a functioning Next.js application running as a single-page application. You aren’t yet leveraging Next.js features like server-side rendering or file-based routing, but you can now do so incrementally:

从 React Router 迁移到 Next.js 应用路由以便：
¥Migrate from React Router to the Next.js App Router for:
- 自动代码拆分
  ¥Automatic code splitting
- 流式服务器渲染
  ¥Streaming server rendering
- React 服务器组件
  ¥React Server Components
使用 <Image> 组件优化图片
¥Optimize images with the <Image> component
使用 next/font 优化字体
¥Optimize fonts with next/font
使用 <Script> 组件优化第三方脚本
¥Optimize third-party scripts with the <Script> component
通过运行 npx next lint 并将其配置为符合项目需求，使用 Next.js 推荐规则启用 ESLint
¥Enable ESLint with Next.js recommended rules by running npx next lint and configuring it to match your project’s needs

注意：使用静态导出 (output: 'export') 目前不支持 useParams 钩子或其他服务器功能。要使用所有 Next.js 功能，请从 next.config.ts 中删除 output: 'export'。
¥Note: Using a static export (output: 'export') does not currently support the useParams hook or other server features. To use all Next.js features, remove output: 'export' from your next.config.ts.

入门

构建你的应用

路由基础知识

数据获取

渲染

样式

优化

配置

测试

部署

升级指南

API 参考

指令

组件

文件约定

元数据文件 API 参考

函数

配置

next.config.js

CLI

入门 - 页面路由

构建你的应用

路由

渲染

数据获取

样式

优化

配置

测试

部署

升级

API 参考

组件

file-conventions

函数

配置

next.config.js 选项

CLI

从 CRA 迁移 ​

为什么要切换？ ​

初始页面加载时间慢 ​

没有自动代码分割 ​

网络瀑布 ​

快速且有意的加载状态 ​

选择数据获取策略 ​

中间件 ​

内置优化 ​

迁移步骤 ​

步骤 1：安装 Next.js 依赖 ​

步骤 2：创建 Next.js 配置文件 ​

步骤 3：创建根布局 ​

步骤 4：元数据 ​

步骤 5：样式 ​

步骤 6：创建入口点页面 ​

步骤 7：添加仅客户端入口点 ​

步骤 8：更新静态图片导入 ​

步骤 9：迁移环境变量 ​

步骤 10：更新 package.json 中的脚本 ​

步骤 11：清理 ​

其他注意事项 ​

在 CRA 中使用自定义 homepage ​

处理自定义 Service Worker ​

代理 API 请求 ​

自定义 Webpack / Babel 配置 ​

TypeScript 设置 ​

打包器兼容性 ​

下一步 ​

从 CRA 迁移

为什么要切换？

初始页面加载时间慢

没有自动代码分割

网络瀑布

快速且有意的加载状态

选择数据获取策略

中间件

内置优化

迁移步骤

步骤 1：安装 Next.js 依赖

步骤 2：创建 Next.js 配置文件

步骤 3：创建根布局

步骤 4：元数据

步骤 5：样式

步骤 6：创建入口点页面

步骤 7：添加仅客户端入口点

步骤 8：更新静态图片导入

步骤 9：迁移环境变量

步骤 10：更新 `package.json` 中的脚本

步骤 11：清理

其他注意事项

在 CRA 中使用自定义 `homepage`

处理自定义 `Service Worker`

代理 API 请求

自定义 Webpack / Babel 配置

TypeScript 设置

打包器兼容性

下一步