跳到主要内容

安装

系统要求​

在开始之前，请确保你的系统满足以下要求：

  • Node.js 18.18 或更高版本。
  • macOS、Windows（包括 WSL）或 Linux。

自动安装​

创建新 Next.js 应用程序的最快方法是使用 create-next-app，它会自动为你设置所有内容。要创建项目，请运行：

Terminal
npx create-next-app@latest

安装时，你会看到以下提示：

Terminal
What is your project named? my-app
Would you like to use TypeScript? No / Yes
Would you like to use ESLint? No / Yes
Would you like to use Tailwind CSS? No / Yes
Would you like your code inside a `src/` directory? No / Yes
Would you like to use App Router? (recommended) No / Yes
Would you like to use Turbopack for `next dev`?  No / Yes
Would you like to customize the import alias (`@/*` by default)? No / Yes
What import alias would you like configured? @/*

提示完成后，create-next-app 将创建一个以你的项目名称命名的文件夹并安装所需的依赖项。

手动安装​

要手动创建新的 Next.js 应用程序，请安装所需的包：

pnpm i next@latest react@latest react-dom@latest

然后，将以下脚本添加到你的 package.json 文件中：

package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}

这些脚本指的是应用程序开发的各个阶段：

  • next dev: 启动开发服务器。
  • next build: 构建应用程序以进行生产。
  • next start: 启动生产服务器。
  • next lint: 运行 ESLint。

创建 app 目录​

Next.js 使用文件系统路由，这意味着你的应用程序的路由由你如何组织文件决定。

创建一个 app 文件夹。然后，在 app 中创建一个 layout.tsx 文件。这个文件是 根布局。它是必需的，必须包含 <html> 和 <body> 标签。

app/layout.tsx

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

创建一个主页 app/page.tsx 并添加一些初始内容：

app/page.tsx
export default function Page() {
  return <h1>你好, Next.js!</h1>
}

layout.tsx 和 page.tsx 都会在用户访问你的应用程序的根目录时（/）被渲染。

App Folder StructureApp Folder Structure

提示:

  • 如果你忘记创建根布局，Next.js 会在运行 next dev 开发服务器时自动创建此文件。
  • 你可以在项目根目录中选择性地使用 src 文件夹 来分离你的应用程序代码和配置文件。

创建 pages 目录​

Next.js 使用文件系统路由，这意味着你的应用程序的路由由你如何组织文件决定。

在项目根目录下创建一个 pages 文件夹。然后，在 pages 文件夹中添加一个 index.tsx 文件。这将是你首页（/）：

pages/index.tsx
export default function Page() {
  return <h1>你好, Next.js!</h1>
}

然后，在 pages/ 中添加一个 _app.tsx 文件，以定义全局布局。了解更多关于 自定义 App 文件。

pages/_app.tsx
import type { AppProps } from 'next/app'

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

最后，在 pages/ 中添加一个 _document.tsx 文件，以控制服务器初始响应。了解更多关于 自定义 Document 文件。

pages/_document.tsx
import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

创建 public 文件夹（可选）​

在项目根目录下创建一个 public 文件夹 来存储静态资产，如图像、字体等。public 文件夹中的文件可以通过你的代码从基础 URL（/）开始引用。

你可以通过根路径（/）引用这些资产。例如，public/profile.png 可以引用为 /profile.png：

app/page.tsx
import Image from 'next/image'

export default function Page() {
  return <Image src="/profile.png" alt="Profile" width={100} height={100} />
}

运行开发服务器​

  1. 运行 npm run dev 启动开发服务器。
  2. 访问 http://localhost:3000 查看你的应用程序。
  3. 编辑 app/page.tsxpages/index.tsx 文件并保存，以在浏览器中查看更新后的结果。

设置 TypeScript​

最小 TypeScript 版本：v4.5.2

Next.js 自带 TypeScript 支持。要向你的项目添加 TypeScript，请将文件重命名为 .ts / .tsx 并运行 next dev。Next.js 将自动安装必要的依赖项并添加一个包含推荐配置选项的 tsconfig.json 文件。

IDE 插件​

Next.js 包含一个自定义 TypeScript 插件和类型检查器，VSCode 和其他代码编辑器可以使用它进行高级类型检查和自动完成。

你可以在 VS Code 中启用插件：

  1. 打开命令面板（Ctrl/⌘ + Shift + P）
  2. 搜索“TypeScript: Select TypeScript Version”
  3. 选择“Use Workspace Version”
TypeScript Command PaletteTypeScript Command Palette

请参阅 TypeScript 参考 页面了解更多信息。

设置 ESLint​

Next.js 自带 ESLint。它会在你使用 create-next-app 创建新项目时自动安装必要的包并配置适当的设置。

要手动向现有项目添加 ESLint，请将 next lint 添加到 package.json 脚本中：

package.json
{
  "scripts": {
    "lint": "next lint"
  }
}

然后，运行 npm run lint，你将看到一个提示，引导你完成安装和配置过程。

Terminal
npm run lint

你会看到一个提示，例如：

? How would you like to configure ESLint?

❯ Strict (recommended) Base Cancel

  • Strict: 包含 Next.js 的基础 ESLint 配置，以及更严格的 Core Web Vitals 规则集。这是首次设置 ESLint 的开发人员推荐配置。
  • Base: 包含 Next.js 的基础 ESLint 配置。
  • Cancel: 跳过配置。如果你计划设置自己的自定义 ESLint 配置，请选择此选项。

如果选择 Strict 或 Base，Next.js 将自动在你的应用程序中安装 eslint 和 eslint-config-next 作为依赖项，并在你的项目根目录下创建一个配置文件。

next lint 生成的 ESLint 配置使用旧的 .eslintrc.json 格式。ESLint 支持 旧的 .eslintrc.json 和新的 eslint.config.mjs 格式。

你可以手动将 .eslintrc.json 替换为 eslint.config.mjs 文件，使用我们在 ESLint API 参考 中推荐的设置，并安装 @eslint/eslintrc 包。这更接近 create-next-app 使用的 ESLint 设置。

你可以随时运行 next lint 来运行 ESLint，以捕获错误。一旦 ESLint 设置完成，它也会自动在每次构建时运行（next build）。错误将导致构建失败，而警告不会。

请参阅 ESLint 插件 页面了解更多信息。

设置绝对导入和模块路径别名​

Next.js 内置支持 tsconfig.json 和 jsconfig.json 文件的 "paths" 和 "baseUrl" 选项。

这些选项允许你将项目目录别名为绝对路径，使导入模块更容易和更清晰。例如：

// 之前
import { Button } from '../../../components/button'

// 之后
import { Button } from '@/components/button'

要配置绝对导入，请将 baseUrl 配置选项添加到你的 tsconfig.json 或 jsconfig.json 文件中。例如：

tsconfig.json 或 jsconfig.json
{
  "compilerOptions": {
    "baseUrl": "src/"
  }
}

除了配置 baseUrl 路径外，你还可以使用 "paths" 选项来别名模块路径。

例如，以下配置将 @/components/* 映射到 components/*：

tsconfig.json 或 jsconfig.json
{
  "compilerOptions": {
    "baseUrl": "src/",
    "paths": {
      "@/styles/*": ["styles/*"],
      "@/components/*": ["components/*"]
    }
  }
}

每个 "paths" 都相对于 baseUrl 位置。

最后于 更新