NNext.js 中文网 GitHub

如何从 Vite 迁移到 Next.js

了解如何将现有的 React 应用程序从 Vite 迁移到 Next.js。

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

为什么要切换?#

你可能出于以下几个原因想要从 Vite 切换到 Next.js:

初始页面加载时间慢#

如果你使用默认的 React Vite 插件构建了应用程序,那么你的应用程序是纯客户端应用程序。纯客户端应用程序(也称为单页应用程序,SPA)通常初始页面加载时间较慢。这主要有两个原因:

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

没有自动代码分割#

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

网络瀑布#

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

虽然 Next.js 支持在客户端获取数据,但它也让你可以选择将数据获取转移到服务器,从而消除客户端-服务器瀑布。

快速且有针对性的加载状态#

借助对通过 React Suspense 进行流式传输的内置支持,你可以更有针对性地决定先加载 UI 的哪些部分以及加载顺序,而不会引入网络瀑布。

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

选择数据获取策略#

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

Proxy#

Next.js Proxy允许你在请求完成之前在服务器上运行代码。当用户访问仅限已身份验证用户访问的页面时,可通过将用户重定向到登录页,避免出现未经身份验证内容的闪现,这一点尤其有用。Proxy 还可用于实验和国际化。

内置优化#

图片、字体和第三方脚本通常对应用程序的性能有重大影响。Next.js 附带了内置组件,可自动为你优化这些内容。

迁移步骤#

本次迁移的目标是尽快获得一个可运行的 Next.js 应用程序,以便你随后逐步采用 Next.js 功能。首先,我们会将其保持为纯客户端应用程序(SPA),而不迁移你现有的路由器。这有助于尽量减少迁移过程中遇到问题的可能性,并减少合并冲突。

第 1 步:安装 Next.js 依赖#

你首先要做的是将 next 安装为依赖:

bash · pnpm
pnpm add next@latest
bash · npm
npm install next@latest
bash · yarn
yarn add next@latest
bash · bun
bun add 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

小知识: 你的 Next.js 配置文件可以使用 .js 或 .mjs。

第 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 设置为 react-jsx:"jsx": "react-jsx"
  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": "react-jsx",
    "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 '...'
}
app/layout.js
export default function RootLayout({ children }) {
  return '...'
}

小知识:布局文件可以使用 .js、.jsx 或 .tsx 扩展名。

  1. 将 index.html 文件的内容复制到之前创建的 <RootLayout> 组件中,同时将 body.div#root 和 body.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>
  )
}
app/layout.js
export default function RootLayout({ children }) {
  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 charset 和 meta 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>
  )
}
app/layout.js
export default function RootLayout({ children }) {
  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.ico、icon.png、robots.txt)只要放在 app 目录的顶层,就会自动添加到应用程序的 <head> 标签中。将所有支持的文件移动到 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>
  )
}
app/layout.js
export default function RootLayout({ children }) {
  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>
  )
}
app/layout.js
export const metadata = {
  title: 'My App',
  description: 'My App is a...',
}

export default function RootLayout({ children }) {
  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 '...' // 稍后会更新这里
}
app/[[...slug]]/page.js
import '../../index.css'

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

export default function Page() {
  return '...' // 稍后会更新这里
}

小知识:页面文件可以使用 .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 />
}
app/[[...slug]]/client.js
'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' 指令定义。Client Component 在发送到客户端之前,仍会在服务器上预渲染为 HTML。

由于我们希望一开始就是纯客户端应用程序,因此可以配置 Next.js,从 App 组件开始禁用预渲染。

tsx
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 />
}
app/[[...slug]]/page.js
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> 组件,通过配置 loader来利用图片优化,或迁移到具有自动图片优化功能的默认 Next.js 服务器。

  1. 将从 /public 导入的图片的绝对路径转换为相对路径:
tsx
// 之前
import logo from '/logo.png'

// 之后
import logo from '../public/logo.png'
  1. 将图片的 src 属性(而不是整个图片对象)传递给你的 <img> 标签:
tsx
// 之前
<img src={logo} />

// 之后
<img src={logo.src} />

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

警告: 如果你使用 TypeScript,在访问 src 属性时可能会遇到类型错误。目前你可以安全地忽略这些错误。本指南结束前会修复它们。

第 7 步:迁移环境变量#

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

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

Turbopack 支持 Vite 内置的 import.meta.env.MODE、DEV、PROD、BASE_URL 和 SSR 属性,无需任何更改。BASE_URL 反映 Next.js 的 basePath 配置,并包含尾部斜杠,与 Vite 的格式一致。

import.meta.glob 受到 Turbopack(Next.js 的默认打包器)支持,无需任何更改。

Turbopack 没有对 Vite 的 ?raw 和 ?url 查询的内置处理,因此 as 选项(在 Vite 5 中已弃用)及其 query 替代方案需要在 next.config.ts 中配置相应的规则:

js
// 之前(Vite)
const modules = import.meta.glob('./dir/*.txt', { as: 'raw' })

// 之后(Next.js / Turbopack)
const modules = import.meta.glob('./dir/*.txt', { query: '?raw' })
next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    rules: {
      // 任何使用 `?raw` 导入的文件都会作为字符串加载
      '*': { condition: { query: '?raw' }, type: 'text' },
    },
  },
}

export default nextConfig

有关完整的 API,请参阅 import.meta.glob 文档。

如果你的 Vite 应用程序配置了自定义基础 URL,请在 next.config.mjs 文件中设置相应的 basePath:

next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // 输出单页应用程序(SPA)。
  distDir: './dist', // 将构建输出目录更改为 `./dist/`。
  basePath: '/some-base-path',
}

export default nextConfig

第 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 上。

示例: 查看这个 pull request,了解 Vite 应用程序迁移到 Next.js 的可运行示例。

第 9 步:清理#

现在你可以从代码库中清理与 Vite 相关的产物:

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

后续步骤#

如果一切按计划进行,你现在拥有一个作为单页应用程序运行的可用 Next.js 应用程序。不过,你尚未利用 Next.js 的大多数优势,但你现在可以开始进行增量更改以获得所有好处。以下是你可能接下来想要做的事情:

Next.js 中文网