如何设置一个新的 Next.js 项目

系统要求

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

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

自动安装

创建新的 Next.js 应用最快的方式是使用 create-next-app，它可以自动为您设置一切。要创建一个项目，请运行

终端

npx create-next-app@latest

安装时，您将看到以下提示

终端

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 应用，请安装所需的包

终端

npm install 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>Hello, Next.js!</h1>
}

当用户访问应用程序的根目录 (/) 时，将渲染 layout.tsx 和 page.tsx。

须知:

如果您忘记创建根布局，Next.js 将在使用 next dev 运行开发服务器时自动创建此文件。

您可以选择在项目根目录中使用 src 目录，以将应用程序的代码与配置文件分开。

创建 `public` 文件夹（可选）

在项目根目录创建一个 public 文件夹，用于存储静态资源，例如图像、字体等。然后，可以从基本 URL (/) 开始，通过代码引用 public 文件夹内的文件。

然后，您可以使用根路径 (/) 引用这些资源。例如，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} />
}

运行开发服务器

运行 npm run dev 以启动开发服务器。
访问 https://127.0.0.1:3000 以查看您的应用程序。
编辑 app/page.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 中启用该插件

打开命令面板 (Ctrl/⌘ + Shift + P)
搜索 "TypeScript: Select TypeScript Version"
选择 "Use Workspace Version"

有关更多信息，请参阅 TypeScript 参考页面。

设置 ESLint

Next.js 内置了 ESLint。当您使用 create-next-app 创建新项目时，它会自动安装必要的包并配置正确的设置。

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

package.json

{
  "scripts": {
    "lint": "next lint"
  }
}

然后，运行 npm run lint，系统将引导您完成安装和配置过程。

终端

npm run lint

您将看到如下提示

? 您想如何配置 ESLint？

❯ 严格 (推荐)
基础
取消

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

如果选择严格或基础，Next.js 将自动在您的应用程序中安装 eslint 和 eslint-config-next 作为依赖项，并在您的项目根目录中创建一个 .eslintrc.json 文件，其中包含您选择的配置。

现在，您可以每次想要运行 ESLint 以捕获错误时都运行 next lint。设置 ESLint 后，它还将在每次构建 (next build) 期间自动运行。错误将导致构建失败，而警告则不会。

有关更多信息，请参阅 ESLint 插件页面。

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

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

这些选项允许您将项目目录别名化为绝对路径，从而更轻松、更简洁地导入模块。例如

// Before
import { Button } from '../../../components/button'
 
// After
import { Button } from '@/components/button'

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

tsconfig.json 或 jsconfig.json

{
  "compilerOptions": {
    "baseUrl": "src/"
  }
}

除了配置 baseUrl 路径之外，您还可以使用 "paths" 选项来 "alias" 模块路径。

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

tsconfig.json 或 jsconfig.json

{
  "compilerOptions": {
    "baseUrl": "src/",
    "paths": {
      "@/styles/*": ["styles/*"],
      "@/components/*": ["components/*"]
    }
  }
}

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