跳到内容

从 Vite 迁移

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

为什么要切换?

您可能想要从 Vite 切换到 Next.js 的原因有几个:

初始页面加载时间过慢

如果您使用 React 的默认 Vite 插件构建了您的应用程序,则您的应用程序是一个纯粹的客户端应用程序。客户端应用程序(也称为单页应用程序 (SPA))通常会遇到初始页面加载时间过慢的问题。发生这种情况的原因有几个:

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

没有自动代码拆分

先前加载时间过慢的问题可以通过代码拆分在某种程度上得到管理。但是,如果您尝试手动进行代码拆分,通常会使性能更差。当手动拆分代码时,很容易无意中引入网络瀑布流。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 作为依赖项

终端
npm install next@latest

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

在您的项目根目录创建一个 next.config.mjs。此文件将保存您的 Next.js 配置选项

next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // Outputs a Single-Page Application (SPA).
  distDir: './dist', // Changes the build output directory to `./dist/`.
}
 
export default nextConfig

须知: 您可以使用 .js.mjs 作为 Next.js 配置文件。

步骤 3:更新 TypeScript 配置

如果您正在使用 TypeScript,则需要更新您的 tsconfig.json 文件,进行以下更改以使其与 Next.js 兼容。如果您没有使用 TypeScript,则可以跳过此步骤。

  1. 删除对 tsconfig.node.json项目引用
  2. ./dist/types/**/*.ts./next-env.d.ts 添加到 include 数组
  3. ./node_modules 添加到 exclude 数组
  4. { "name": "next" } 添加到 compilerOptions 中的 plugins 数组"plugins": [{ "name": "next" }]
  5. esModuleInterop 设置为 true"esModuleInterop": true
  6. jsx 设置为 preserve"jsx": "preserve"
  7. allowJs 设置为 true"allowJs": true
  8. forceConsistentCasingInFileNames 设置为 true"forceConsistentCasingInFileNames": true
  9. incremental 设置为 true"incremental": true

以下是一个使用这些更改的工作正常的 tsconfig.json 示例

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "preserve",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "allowJs": true,
    "forceConsistentCasingInFileNames": true,
    "incremental": true,
    "plugins": [{ "name": "next" }]
  },
  "include": ["./src", "./dist/types/**/*.ts", "./next-env.d.ts"],
  "exclude": ["./node_modules"]
}

您可以在 Next.js 文档中找到有关配置 TypeScript 的更多信息。

步骤 4:创建根布局

Next.js App Router 应用程序必须包含一个根布局文件,这是一个 React Server Component,它将包装您应用程序中的所有页面。此文件在 app 目录的顶层定义。

Vite 应用程序中与根布局文件最接近的等效项是 index.html 文件,其中包含您的 <html><head><body> 标签。

在此步骤中,您将把 index.html 文件转换为根布局文件

  1. 在您的 src 目录中创建一个新的 app 目录。
  2. 在该 app 目录中创建一个新的 layout.tsx 文件
app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return '...'
}

须知.js.jsx.tsx 扩展名可用于布局文件。

  1. index.html 文件的内容复制到先前创建的 <RootLayout> 组件中,同时将 body.div#rootbody.script 标签替换为 <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" 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>
  )
}
  1. Next.js 默认已包含 meta charsetmeta viewport 标签,因此您可以安全地从 <head> 中删除这些标签
app/layout.tsx
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>
  )
}
  1. 任何元数据文件(例如 favicon.icoicon.pngrobots.txt)都会自动添加到应用程序 <head> 标签中,只要您将它们放置在 app 目录的顶层即可。在将 所有支持的文件移动到 app 目录后,您可以安全地删除它们的 <link> 标签
app/layout.tsx
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>
  )
}
  1. 最后,Next.js 可以使用 Metadata API 管理您最后的 <head> 标签。将您最后的元数据信息移动到导出的 metadata 对象
app/layout.tsx
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 方法 (Metadata API)。这种方法使您能够更轻松地改进页面的 SEO 和 Web 可分享性。

步骤 5:创建入口点页面

在 Next.js 上,您可以通过创建一个 page.tsx 文件来声明应用程序的入口点。Vite 上此文件最接近的等效项是您的 main.tsx 文件。在此步骤中,您将设置应用程序的入口点。

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

由于在本指南中,我们的首要目标是将 Next.js 设置为 SPA(单页应用程序),因此您需要您的页面入口点来捕获应用程序的所有可能路由。为此,在您的 app 目录中创建一个新的 [[...slug]] 目录。

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

  1. app/[[...slug]] 目录中创建一个新的 page.tsx 文件,内容如下
app/[[...slug]]/page.tsx
import '../../index.css'
 
export function generateStaticParams() {
  return [{ slug: [''] }]
}
 
export default function Page() {
  return '...' // We'll update this
}

须知.js.jsx.tsx 扩展名可用于页面文件。

此文件是 Server Component。当您运行 next build 时,该文件会被预渲染为静态资源。它需要任何动态代码。

此文件导入我们的全局 CSS 并告诉 generateStaticParams 我们只会生成一个路由,即 / 处的索引路由。

现在,让我们移动我们 Vite 应用程序的其余部分,这些部分将仅在客户端运行。

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

此文件是 Client Component,由 'use client' 指令定义。客户端组件仍然在发送到客户端之前,在服务器上预渲染为 HTML

由于我们希望启动一个仅客户端的应用程序,因此我们可以配置 Next.js 以禁用从 App 组件向下预渲染。

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

现在,更新您的入口点页面以使用新组件

app/[[...slug]]/page.tsx
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` will be '/assets/img.2d8efhg.png' in production
 
export default function App() {
  return <img src={image} />
}

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

<Image> 组件还具有自动图像优化的额外优势。<Image> 组件会根据图像的尺寸自动设置生成的 <img>widthheight 属性。这可以防止图像加载时出现布局偏移。但是,如果您的应用程序包含仅对其尺寸之一进行样式设置而另一个尺寸未设置为 auto 的图像,则可能会导致问题。当未设置为 auto 时,尺寸将默认为 <img> 尺寸属性的值,这可能会导致图像显得失真。

保留 <img> 标签将减少应用程序中的更改量,并防止上述问题。然后,您可以选择稍后迁移到 <Image> 组件,以通过配置加载器或迁移到具有自动图像优化的默认 Next.js 服务器来利用优化图像的优势。

  1. 将从 /public 导入的图像的绝对导入路径转换为相对导入
// Before
import logo from '/logo.png'
 
// After
import logo from '../public/logo.png'
  1. 传递图像 src 属性,而不是整个图像对象到您的 <img> 标签
// Before
<img src={logo} />
 
// After
<img src={logo.src} />

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

警告: 如果您正在使用 TypeScript,则在访问 src 属性时可能会遇到类型错误。您可以暂时忽略这些错误。在本指南结束时,这些错误将被修复。

步骤 7:迁移环境变量

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

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

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

  • import.meta.env.MODEprocess.env.NODE_ENV
  • import.meta.env.PRODprocess.env.NODE_ENV === 'production'
  • import.meta.env.DEVprocess.env.NODE_ENV !== 'production'
  • import.meta.env.SSRtypeof window !== 'undefined'

Next.js 也不提供内置的 BASE_URL 环境变量。但是,如果您需要,仍然可以配置一个。

  1. 将以下内容添加到您的 .env 文件中
.env
# ...
NEXT_PUBLIC_BASE_PATH="/some-base-path"
  1. 在您的 next.config.mjs 文件中,将 basePath 设置为 process.env.NEXT_PUBLIC_BASE_PATH
next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // Outputs a Single-Page Application (SPA).
  distDir: './dist', // Changes the build output directory to `./dist/`.
  basePath: process.env.NEXT_PUBLIC_BASE_PATH, // Sets the base path to `/some-base-path`.
}
 
export default nextConfig
  1. import.meta.env.BASE_URL 的用法更新为 process.env.NEXT_PUBLIC_BASE_PATH

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

现在您应该能够运行您的应用程序,以测试您是否已成功迁移到 Next.js。但在那之前,您需要在 package.json 中使用 Next.js 相关命令更新您的 scripts,并将 .nextnext-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,并打开 https://127.0.0.1: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 的大部分优势,但您现在可以开始进行增量更改以获得所有好处。以下是您接下来可能想要做的事情: