从 React 到 Next.js：无缝迁移与实践教程 – wiki大全

作者： /

从 React 到 Next.js：无缝迁移与实践教程

在现代 Web 开发中，React 已经成为构建用户界面的首选库。然而，随着应用复杂度的提升，我们常常需要处理路由、数据获取、服务端渲染（SSR）或静态站点生成（SSG）等问题。Next.js 作为基于 React 的生产级框架，优雅地解决了这些问题，并提供了开箱即用的最佳实践。

本文将详细探讨为什么以及如何将一个现有的 React 项目（通常由 Create React App 构建）无缝迁移到 Next.js，并提供一份详尽的实践教程。

为什么要迁移到 Next.js？

与纯粹的 React 库相比，Next.js 提供了以下核心优势：

  1. 多种渲染方式：支持 服务端渲染 (SSR)、静态站点生成 (SSG) 和 客户端渲染 (CSR)，你可以根据页面需求灵活选择，极大地优化了首屏加载速度和 SEO。
  2. 基于文件的路由系统：无需再配置 react-router-dom。pages 目录下的文件结构自动映射为 URL 路由，简洁直观。
  3. API 路由：可以在 pages/api 目录下创建 Serverless Functions，轻松构建后端 API 接口，无需独立的 Node.js 服务器。
  4. 图片优化：内置的 <Image> 组件可以自动优化图片大小、格式和加载方式，提升网站性能和用户体验。
  5. 代码拆分：自动按页面进行代码拆分，只加载当前页面必需的 JavaScript，减少不必要的负载。
  6. 内置 CSS 和 Sass 支持：支持模块化 CSS、全局 CSS 以及 Sass，配置简单。
  7. 环境配置简单：开箱即用，无需复杂的 Webpack 和 Babel 配置，让开发者专注于业务逻辑。

迁移实践教程

接下来，我们将一步步地将一个用 Create React App (CRA) 创建的典型 React 项目迁移到 Next.js。

第 1 步：准备工作

假设你的项目结构如下：

my-react-app/
├── node_modules/
├── public/
│ ├── index.html
│ └── favicon.ico
├── src/
│ ├── components/
│ │ ├── Header.js
│ │ └── Layout.js
│ ├── pages/
│ │ ├── HomePage.js
│ │ └── AboutPage.js
│ ├── App.css
│ ├── App.js
│ ├── index.css
│ └── index.js
├── package.json
└── ...

第 2 步：安装 Next.js 并更新 package.json

首先，安装 Next.js 依赖：

“`bash
npm install next

或者

yarn add next
“`

然后，修改 package.json 中的 scripts：

“`json
// package.json

“scripts”: {
“dev”: “next dev”,
“build”: “next build”,
“start”: “next start”,
“lint”: “next lint”
}
“`

现在你可以卸载 react-scripts，因为它不再被需要：

“`bash
npm uninstall react-scripts

或者

yarn remove react-scripts
“`

第 3 步：创建 Next.js 的目录结构

Next.js 依赖特定的文件夹结构。最核心的是 pages 目录。

  1. 重命名 src 目录（可选但推荐）：Next.js 支持将应用代码放在根目录或 src 目录。如果你的代码已经在 src 中，可以保留。如果不在，建议将所有组件、页面等逻辑都移入 src。

  2. 创建 pages 目录：这是 Next.js 最重要的约定。

    • 在项目根目录（或 src 目录）下创建一个 pages 目录。
    • 之前 CRA 中的 public/index.html 文件可以删除了，Next.js 会自动处理 HTML 的生成。
    • CRA 中的 src/index.js 也不再需要，Next.js 有自己的入口点。

  3. 创建 _app.js 和 _document.js

    • pages/_app.js：这是所有页面的根组件，类似于 CRA 中的 App.js。你可以用它来包裹所有页面，注入全局 CSS，或者传递全局状态。
    • pages/_document.js：用于自定义服务器返回的 HTML 文档结构，比如修改 <html> 和 <body> 标签。这通常是可选的。

一个基本的 _app.js 如下：

“`jsx
// src/pages/_app.js

// 引入全局样式
import ‘../styles/globals.css’;

function MyApp({ Component, pageProps }) {
// Component 是当前页面的组件
// pageProps 是传递给该页面的 props
return ;
}

export default MyApp;
“`

将你的 App.css 或 index.css 的内容整合到一个新的全局样式文件（如 src/styles/globals.css）并在这里引入。

第 4 步：迁移页面和路由

Next.js 的路由系统是基于文件系统的。pages 目录下的每个 React 组件都会成为一个页面。

  • pages/index.js -> /
  • pages/about.js -> /about
  • pages/posts/[id].js -> /posts/:id (动态路由)

将你 CRA 项目中 src/pages 里的 HomePage.js 和 AboutPage.js 迁移过来：

  1. 将 src/pages/HomePage.js 的内容移动到 src/pages/index.js。
  2. 将 src/pages/AboutPage.js 的内容移动到 src/pages/about.js。

重要：
* 在 Next.js 中，页面组件必须 默认导出 (default export)。
* 删除所有与 react-router-dom 相关的代码，如 BrowserRouter, Route, Switch。

第 5 步：处理链接和导航

使用 next/link 替代 react-router-dom 的 Link。

之前 (React Router):

“`jsx
import { Link } from ‘react-router-dom’;

function Header() {
return (

);
}
“`

之后 (Next.js):

“`jsx
import Link from ‘next/link’;

function Header() {
return (

);
}
// 注意：在 Next.js 的较新版本中， 标签可以省略
// Home
“`

第 6 步：处理静态资源和 CSS

  1. 公共资源：将 CRA public 目录下的所有静态资源（如 favicon.ico, robots.txt）移动到 Next.js 项目根目录下的 public 目录。Next.js 会自动托管这些文件。

  2. 全局 CSS：如第 3 步所述，在 pages/_app.js 中引入全局样式文件。

  3. 组件级 CSS：Next.js 内置支持 CSS Modules。将你的 CSS 文件命名为 [componentName].module.css 即可。

    示例：

    css
    /* src/components/Button.module.css */
    .error {
    color: white;
    background-color: red;
    }

    “`jsx
    / src/components/Button.js /
    import styles from ‘./Button.module.css’;

    export function Button() {
    return (

    );
    }
    “`

第 7 步：数据获取

这是迁移过程中最关键的一步。CRA 通常使用 useEffect 在客户端获取数据，这会导致加载状态和 SEO 问题。Next.js 提供了更强大的数据获取方法。

  • getStaticProps (SSG)：在 构建时 获取数据，生成静态页面。适用于博客文章、文档、营销页面等内容不经常变化的场景。

    “`jsx
    // src/pages/posts.js
    export async function getStaticProps() {
    const res = await fetch(‘https://api.example.com/posts’);
    const posts = await res.json();

    return {
    props: {
    posts, // posts 将作为 props 传递给页面组件
    },
    };
    }

    function Blog({ posts }) {
    // 渲染 posts…
    }
    “`

  • getServerSideProps (SSR)：在 每次请求时 在服务器端获取数据。适用于需要实时数据的页面，如用户仪表盘。

    “`jsx
    // src/pages/dashboard.js
    export async function getServerSideProps(context) {
    const { req, res } = context; // 可以访问请求和响应对象
    const data = await fetchFromPrivateAPI(req.headers.cookie);

    return {
    props: { data }, // data 将作为 props 传递给页面组件
    };
    }

    function Dashboard({ data }) {
    // 渲染 data…
    }
    “`

将之前在 useEffect 中的数据请求逻辑，根据页面需求迁移到这两个函数中。

第 8 步：处理 <head>

在 CRA 中，你可能使用 react-helmet 等库来管理 <head> 标签。在 Next.js 中，使用内置的 next/head 组件。

“`jsx
import Head from ‘next/head’;

function AboutPage() {
return (


About Us | My Awesome Site

About Us

);
}
“`

第 9 步：环境变量

在 CRA 中，环境变量以 REACT_APP_ 开头。在 Next.js 中：
* 默认情况下，.env.local 中的所有变量都只能在服务器端（getStaticProps, getServerSideProps）访问。
* 如果想在浏览器客户端访问，必须以 NEXT_PUBLIC_ 作为前缀。

修改你的环境变量命名，并更新代码中的引用。

结论

从 React (CRA) 迁移到 Next.js 是一个平滑且回报丰厚的过程。它不仅能显著提升应用性能、改善 SEO，还能简化开发工作流。通过遵循上述步骤——调整项目结构、更新路由和链接、迁移数据获取逻辑——你就可以充分利用 Next.js 带来的强大功能，构建更快、更现代的 Web 应用。

虽然初期需要一些学习和调整，但 Next.js 提供的开发体验和最终产品质量的提升，将证明这次迁移是完全值得的。

滚动至顶部