如何从 Vite 迁移到 Next.js

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

为何切换？

您可能希望从 Vite 切换到 Next.js 的原因有以下几点：

初始页面加载时间慢

如果您使用 React 默认的 Vite 插件构建了您的应用程序，那么您的应用程序将是一个纯客户端应用程序。纯客户端应用程序，也称为单页应用程序 (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 作为依赖项：

bash

npm install next@latest

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

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

javascript

/** @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

须知： 您的 Next.js 配置文件可以使用 .js 或 .mjs 扩展名。

步骤 3：更新 TypeScript 配置

如果您正在使用 TypeScript，您需要对 tsconfig.json 文件进行以下更改，以使其与 Next.js 兼容。如果您不使用 TypeScript，可以跳过此步骤。

移除 tsconfig.node.json 的项目引用
将 ./dist/types/**/*.ts 和 ./next-env.d.ts 添加到 include 数组中
将 ./node_modules 添加到 exclude 数组中
将 { "name": "next" } 添加到 compilerOptions 中的 plugins 数组："plugins": [{ "name": "next" }]
将 esModuleInterop 设置为 true："esModuleInterop": true
将 jsx 设置为 react-jsx："jsx": "react-jsx"
将 allowJs 设置为 true："allowJs": true
将 forceConsistentCasingInFileNames 设置为 true："forceConsistentCasingInFileNames": true
将 incremental 设置为 true："incremental": true

这是一个包含上述更改的 tsconfig.json 示例：

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 服务器组件，将包裹您应用程序中的所有页面。此文件定义在 app 目录的顶层。

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

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

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

tsx

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

jsx

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

须知：布局文件可以使用 .js、.jsx 或 .tsx 扩展名。

将 index.html 文件的内容复制到之前创建的 <RootLayout> 组件中，同时将 body.div#root 和 body.script 标签替换为 <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" 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>
  )
}

jsx

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

Next.js 默认已经包含了 meta charset 和 meta viewport 标签，因此您可以安全地从 <head> 中移除它们：

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

jsx

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

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

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

jsx

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

最后，Next.js 可以使用 Metadata API 管理您剩余的 <head> 标签。将您最终的元数据信息移动到一个导出的 metadata 对象中：

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

jsx

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 和网络可分享性。

步骤 5：创建入口页面

在 Next.js 中，您通过创建 page.tsx 文件来声明应用程序的入口点。在 Vite 中，与此文件最接近的是您的 main.tsx 文件。在此步骤中，您将设置应用程序的入口点。

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

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

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

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

tsx

import '../../index.css'

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

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

jsx

import '../../index.css'

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

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

须知：页面文件可以使用 .js、.jsx 或 .tsx 扩展名。

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

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

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

tsx

'use client'

import React from 'react'
import dynamic from 'next/dynamic'

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

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

jsx

'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 组件开始的预渲染。

tsx

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

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

tsx

import '../../index.css'
import { ClientOnly } from './client'

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

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

jsx

import '../../index.css'
import { ClientOnly } from './client'

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

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

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

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

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> 的 width 和 height 属性。这可以防止图片加载时出现布局偏移。然而，如果您的应用程序中包含的图片只有一个维度被样式化，而另一个维度没有设置为 auto，这可能会导致问题。当没有设置为 auto 时，该维度将默认为 <img> 尺寸属性的值，这可能导致图片失真。

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

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

tsx

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

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

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

tsx

// 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.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 文件中：

bash

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

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

javascript

/** @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

将 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 中：

json

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

txt

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

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

示例： 请参阅此拉取请求，了解一个已迁移到 Next.js 的 Vite 应用程序的实际示例。

步骤 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 规则

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

为何切换？

您可能希望从 Vite 切换到 Next.js 的原因有以下几点：

初始页面加载时间慢

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

没有自动代码分割

网络瀑布

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

快速且有意的加载状态

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

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

选择数据获取策略

代理

内置优化

图片、字体和第三方脚本通常对应用程序的性能有显著影响。Next.js 提供了内置组件，可自动为您优化这些资源。

迁移步骤

步骤 1：安装 Next.js 依赖

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

bash

npm install next@latest

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

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

javascript

/** @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

须知： 您的 Next.js 配置文件可以使用 .js 或 .mjs 扩展名。

步骤 3：更新 TypeScript 配置

如果您正在使用 TypeScript，您需要对 tsconfig.json 文件进行以下更改，以使其与 Next.js 兼容。如果您不使用 TypeScript，可以跳过此步骤。

移除 tsconfig.node.json 的项目引用
将 ./dist/types/**/*.ts 和 ./next-env.d.ts 添加到 include 数组中
将 ./node_modules 添加到 exclude 数组中
将 { "name": "next" } 添加到 compilerOptions 中的 plugins 数组："plugins": [{ "name": "next" }]
将 esModuleInterop 设置为 true："esModuleInterop": true
将 jsx 设置为 react-jsx："jsx": "react-jsx"
将 allowJs 设置为 true："allowJs": true
将 forceConsistentCasingInFileNames 设置为 true："forceConsistentCasingInFileNames": true
将 incremental 设置为 true："incremental": true

这是一个包含上述更改的 tsconfig.json 示例：

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 服务器组件，将包裹您应用程序中的所有页面。此文件定义在 app 目录的顶层。

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

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

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

tsx

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

jsx

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

须知：布局文件可以使用 .js、.jsx 或 .tsx 扩展名。

将 index.html 文件的内容复制到之前创建的 <RootLayout> 组件中，同时将 body.div#root 和 body.script 标签替换为 <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" 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>
  )
}

jsx

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

Next.js 默认已经包含了 meta charset 和 meta viewport 标签，因此您可以安全地从 <head> 中移除它们：

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

jsx

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

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

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

jsx

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

最后，Next.js 可以使用 Metadata API 管理您剩余的 <head> 标签。将您最终的元数据信息移动到一个导出的 metadata 对象中：

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

jsx

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

步骤 5：创建入口页面

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

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

tsx

import '../../index.css'

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

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

jsx

import '../../index.css'

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

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

须知：页面文件可以使用 .js、.jsx 或 .tsx 扩展名。

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

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

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

tsx

'use client'

import React from 'react'
import dynamic from 'next/dynamic'

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

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

jsx

'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 组件开始的预渲染。

tsx

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

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

tsx

import '../../index.css'
import { ClientOnly } from './client'

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

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

jsx

import '../../index.css'
import { ClientOnly } from './client'

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

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

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

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

tsx

import image from './img.png' // `image` will be '/assets/img.2d8efhg.png' in production

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

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

tsx

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

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

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

tsx

// 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.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 文件中：

bash

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

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

javascript

/** @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

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

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

json

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

txt

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

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

示例： 请参阅此拉取请求，了解一个已迁移到 Next.js 的 Vite 应用程序的实际示例。

步骤 9：清理

您现在可以从代码库中清理与 Vite 相关的遗留文件：

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

后续步骤

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

文档导航

为何切换？

初始页面加载时间慢

没有自动代码分割

网络瀑布

快速且有意的加载状态

选择数据获取策略

代理

内置优化

迁移步骤

步骤 1：安装 Next.js 依赖

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

步骤 3：更新 TypeScript 配置

步骤 4：创建根布局

步骤 5：创建入口页面

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

步骤 7：迁移环境变量

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

步骤 9：清理

后续步骤

为何切换？

初始页面加载时间慢

没有自动代码分割

网络瀑布

快速且有意的加载状态

选择数据获取策略

代理

内置优化

迁移步骤

步骤 1：安装 Next.js 依赖

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

步骤 3：更新 TypeScript 配置

步骤 4：创建根布局

步骤 5：创建入口页面

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

步骤 7：迁移环境变量

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

步骤 9：清理

后续步骤

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

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