Menu

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

系统要求

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

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

Terminal
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
TypeScript
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

创建一个带有初始内容的主页 app/page.tsx

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

当用户访问你的应用程序根目录(/)时,layout.tsxpage.tsx 都将被渲染。

App Folder Structure

值得注意的是

  • 如果你忘记创建根布局,Next.js 会在使用 next dev 运行开发服务器时自动创建这个文件。
  • 你可以选择在项目根目录中使用 src 目录,以将应用程序代码与配置文件分开。

创建 public 文件夹(可选)

在项目根目录创建一个 public 文件夹,用于存储静态资源,如图片、字体等。public 中的文件可以从基础 URL(/)开始被你的代码引用。

你可以使用根路径(/)引用这些资源。例如,public/profile.png 可以被引用为 /profile.png

app/page.tsx
TypeScript
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.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 Palette

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

设置 ESLint

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

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

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 配置,请选择此选项。

如果选择了 StrictBase,Next.js 将自动安装 eslinteslint-config-next 作为应用程序的依赖项,并在项目根目录创建一个包含所选配置的 .eslintrc.json 文件。

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

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

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

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

这些选项允许你将项目目录别名为绝对路径,使模块导入更简单、更清晰。例如:

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

要配置绝对导入,请在 tsconfig.jsonjsconfig.json 文件中添加 baseUrl 配置选项。例如:

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

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

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

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

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