Migrating from Vite

本指南将帮助你将现有的 Vite 应用迁移到 Next.js。

为什么要切换？

有几个原因可能让你想要从 Vite 切换到 Next.js：

初始页面加载时间慢

如果你使用默认的 Vite React 插件构建应用，你的应用是一个纯客户端应用。仅客户端的应用，也被称为单页应用（SPAs），通常会遇到初始页面加载时间慢的问题。这发生的原因有几个：

浏览器需要等待 React 代码和你的整个应用包下载并运行，然后你的代码才能发送请求加载数据。
随着每个新功能和额外依赖的添加，你的应用代码会不断增长。

没有自动代码分割

前面提到的加载时间慢的问题可以通过代码分割在一定程度上得到管理。然而，如果你尝试手动进行代码分割，你通常会使性能变得更糟。在手动代码分割时，很容易无意中引入网络瀑布流。Next.js 在其路由器中内置了自动代码分割功能。

网络瀑布流

应用性能不佳的一个常见原因是应用程序进行顺序的客户端-服务器请求来获取数据。SPA 中数据获取的一个常见模式是初始渲染一个占位符，然后在组件挂载后获取数据。不幸的是，这意味着获取数据的子组件必须等到父组件完成加载自己的数据后才能开始获取。

虽然 Next.js 支持在客户端获取数据，但它也为你提供了将数据获取转移到服务器的选项，这可以消除客户端-服务器瀑布流。

快速且有意图的加载状态

通过对React Suspense 的流式传输的内置支持，你可以更有意图地决定你希望首先加载 UI 的哪些部分以及加载的顺序，而不会引入网络瀑布流。

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

选择数据获取策略

根据你的需求，Next.js 允许你在页面和组件基础上选择数据获取策略。你可以决定在构建时、服务器请求时或客户端获取数据。例如，你可以在构建时从 CMS 获取数据并渲染你的博客文章，然后这些文章可以在 CDN 上高效缓存。

中间件

Next.js 中间件允许你在请求完成前在服务器上运行代码。这对于避免在用户访问仅认证页面时出现未认证内容的闪烁特别有用，可以通过将用户重定向到登录页面来实现。中间件对于实验和国际化也很有用。

内置优化

图像、字体和第三方脚本通常对应用性能有显著影响。Next.js 提供了内置组件，可以自动为你优化这些内容。

迁移步骤

我们进行这次迁移的目标是尽快获得一个可工作的 Next.js 应用，这样你就可以逐步采用 Next.js 的功能。首先，我们将保持它作为一个纯客户端应用（SPA），而不迁移你现有的路由器。这有助于最小化迁移过程中遇到问题的可能性，并减少合并冲突。

步骤 1：安装 Next.js 依赖

你需要做的第一件事是安装 next 作为依赖：

Terminal

npm install next@latest

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

在项目根目录创建 next.config.mjs。这个文件将包含你的 Next.js 配置选项。

next.config.mjs

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // 输出单页应用（SPA）。
  distDir: './dist', // 将构建输出目录更改为 `./dist/`。
}
 
export default nextConfig

值得注意的是： 你可以使用 .js 或 .mjs 作为 Next.js 配置文件。

步骤 4：创建根布局

Next.js App Router 应用必须包含一个根布局文件，这是一个将包裹应用中所有页面的 React 服务器组件。这个文件定义在 app 目录的顶层。

Vite 应用中与根布局文件最接近的等效项是 index.html 文件，其中包含了你的 <html>、<head> 和 <body> 标签。

在这一步，你将把 index.html 文件转换为根布局文件：

在 src 目录中创建一个新的 app 目录。
在该 app 目录内创建一个新的 layout.tsx 文件：

app/layout.tsx

TypeScript

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

值得注意的是：布局文件可以使用 .js、.jsx 或 .tsx 扩展名。

将 index.html 文件的内容复制到之前创建的 <RootLayout> 组件中，同时将 body.div#root 和 body.script 标签替换为 <div id="root">{children}</div>：

app/layout.tsx

TypeScript

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" type="image/svg+xml" href="/icon.svg" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>My App</title>
        <meta name="description" content="My App is a..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

Next.js 已经默认包含 meta charset 和 meta viewport 标签，所以你可以安全地从 <head> 中删除这些标签：

app/layout.tsx

TypeScript

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head>
        <link rel="icon" type="image/svg+xml" href="/icon.svg" />
        <title>My App</title>
        <meta name="description" content="My App is a..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

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

app/layout.tsx

TypeScript

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head>
        <title>My App</title>
        <meta name="description" content="My App is a..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

最后，Next.js 可以通过元数据 API 管理你的最后 <head> 标签。将你的最终元数据信息移动到导出的 metadata 对象中：

app/layout.tsx

TypeScript

import type { Metadata } from 'next'
 
export const metadata: Metadata = {
  title: 'My App',
  description: 'My App is a...',
}
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

通过上述更改，你从在 index.html 中声明所有内容转变为使用 Next.js 框架内置的基于约定的方法 (元数据 API)。这种方法使你能够更轻松地改进页面的 SEO 和网络共享能力。

步骤 5：创建入口点页面

在 Next.js 中，你通过创建 page.tsx 文件来声明应用的入口点。 Vite 中与此文件最接近的等效项是 main.tsx 文件。在这一步，你将设置应用的入口点。

在 app 目录中创建一个 [[...slug]] 目录。

由于在本指南中我们首先旨在将 Next.js 设置为 SPA（单页应用程序），你需要你的页面入口点能够捕获应用程序的所有可能路由。为此，在 app 目录中创建一个新的 [[...slug]] 目录。

这个目录是所谓的可选捕获所有路由段。Next.js 使用基于文件系统的路由器，其中文件夹用于定义路由。这个特殊目录将确保应用程序的所有路由都指向其包含的 page.tsx 文件。

在 app/[[...slug]] 目录中创建一个新的 page.tsx 文件，内容如下：

app/[[...slug]]/page.tsx

TypeScript

import '../../index.css'
 
export function generateStaticParams() {
  return [{ slug: [''] }]
}
 
export default function Page() {
  return '...' // 我们将更新这部分
}

值得注意的是：页面文件可以使用 .js、.jsx 或 .tsx 扩展名。

这个文件是一个服务器组件。当你运行 next build 时，该文件会被预渲染成静态资源。它_不_需要任何动态代码。

这个文件导入我们的全局 CSS，并告诉 generateStaticParams 我们只打算生成一个路由，即位于 / 的索引路由。

现在，让我们移动我们 Vite 应用的其余部分，它将只在客户端运行。

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

TypeScript

'use client'
 
import React from 'react'
import dynamic from 'next/dynamic'
 
const App = dynamic(() => import('../../App'), { ssr: false })
 
export function ClientOnly() {
  return <App />
}

这个文件是一个客户端组件，由 'use client' 指令定义。客户端组件仍然会在发送到客户端之前在服务器上预渲染为 HTML。

由于我们想要一个仅客户端的应用程序作为起点，我们可以配置 Next.js 禁用从 App 组件向下的预渲染。

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

现在，更新你的入口点页面以使用新组件：

app/[[...slug]]/page.tsx

TypeScript

import '../../index.css'
import { ClientOnly } from './client'
 
export function generateStaticParams() {
  return [{ slug: [''] }]
}
 
export default function Page() {
  return <ClientOnly />
}

步骤 6：更新静态图像导入

Next.js 处理静态图像导入的方式与 Vite 略有不同。在 Vite 中，导入图像文件将返回其公共 URL 作为字符串：

App.tsx

import image from './img.png' // 在生产中 `image` 将是 '/assets/img.2d8efhg.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> 组件，以通过配置加载器来利用图像优化，或者切换到默认的 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 属性时可能会遇到类型错误。你可以暂时安全地忽略这些错误。到本指南结束时，它们将被修复。

步骤 7：迁移环境变量

Next.js 支持与 Vite 类似的 .env 环境变量。主要区别在于用于在客户端公开环境变量的前缀。

将所有带有 VITE_ 前缀的环境变量更改为 NEXT_PUBLIC_。

Vite 在特殊的 import.meta.env 对象上公开了一些内置环境变量，这些变量不被 Next.js 支持。你需要按如下方式更新它们的使用：

import.meta.env.MODE ⇒ process.env.NODE_ENV
import.meta.env.PROD ⇒ process.env.NODE_ENV === 'production'
import.meta.env.DEV ⇒ process.env.NODE_ENV !== 'production'
import.meta.env.SSR ⇒ typeof window !== 'undefined'

Next.js 也不提供内置的 BASE_URL 环境变量。然而，如果你需要，你仍然可以配置一个：

在你的 .env 文件中添加以下内容：

.env

# ...
NEXT_PUBLIC_BASE_PATH="/some-base-path"

在你的 next.config.mjs 文件中将 basePath 设置为 process.env.NEXT_PUBLIC_BASE_PATH：

next.config.mjs

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // 输出单页应用（SPA）。
  distDir: './dist', // 将构建输出目录更改为 `./dist/`。
  basePath: process.env.NEXT_PUBLIC_BASE_PATH, // 将基本路径设置为 `/some-base-path`。
}
 
export default nextConfig

将 import.meta.env.BASE_URL 的使用更新为 process.env.NEXT_PUBLIC_BASE_PATH

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

你现在应该能够运行你的应用程序来测试是否成功迁移到 Next.js。但在此之前，你需要用 Next.js 相关命令更新 package.json 中的 scripts，并将 .next 和 next-env.d.ts 添加到你的 .gitignore 中：

package.json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

.gitignore

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

现在运行 npm run dev，并打开 http://localhost:3000。你应该看到你的应用程序现在运行在 Next.js 上了。

示例： 查看这个拉取请求获取一个 Vite 应用迁移到 Next.js 的工作示例。

步骤 9：清理

现在你可以清理你的代码库中与 Vite 相关的工件：

删除 main.tsx
删除 index.html
删除 vite-env.d.ts
删除 tsconfig.node.json
删除 vite.config.ts
卸载 Vite 依赖

下一步

如果一切按计划进行，你现在拥有一个作为单页应用程序运行的功能齐全的 Next.js 应用程序。然而，你还没有利用 Next.js 的大部分优势，但你现在可以开始进行增量更改以获得所有好处。以下是你可能想要做的下一步：

从 React Router 迁移到 Next.js App Router 以获得：
- 自动代码分割
- 流式服务器渲染
- React 服务器组件
使用 <Image> 组件优化图像
使用 next/font 优化字体
使用 <Script> 组件优化第三方脚本
更新你的 ESLint 配置以支持 Next.js 规则