如何新建 Next.js 项目

系统要求

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

Node.js 18.18 或更高版本
macOS、Windows（含 WSL）或 Linux 系统

自动安装

创建 Next.js 应用最快的方式是使用 create-next-app，它会自动为您完成所有设置。运行以下命令创建项目：

终端

npx create-next-app@latest

安装过程中会显示以下提示：

终端

请输入项目名称？my-app
是否使用 TypeScript？否 / 是
是否使用 ESLint？否 / 是
是否使用 Tailwind CSS？否 / 是
是否将代码放在 `src/` 目录下？否 / 是
是否使用 App Router？（推荐）否 / 是
是否在 `next dev` 中使用 Turbopack？否 / 是
是否自定义导入别名（默认为 `@/*`）？否 / 是
请输入配置的导入别名？@/*

完成提示后，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 文件夹后，在其中添加 layout.tsx 文件作为根布局。该文件必须包含 <html> 和 <body> 标签。

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

创建首页内容 app/page.tsx：

export default function Page() {
  return <h1>你好，Next.js！</h1>
}

当用户访问应用根路径（/）时，layout.tsx 和 page.tsx 将同时被渲染。

须知：

如果忘记创建根布局，运行 next dev 启动开发服务器时 Next.js 会自动生成此文件

可选择在项目根目录使用 src 文件夹来分离应用代码与配置文件

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

在项目根目录创建 public 文件夹存放静态资源如图片、字体等。public 中的文件可通过根路径（/）引用。

例如 public/profile.png 可引用为 /profile.png：

import Image from 'next/image'

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

运行开发服务器

执行 npm run dev 启动开发服务器
访问 http://localhost: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: 选择 TypeScript 版本"
选择 "使用工作区版本"

更多信息请参考 TypeScript 参考文档。

配置 ESLint

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

要为现有项目手动添加 ESLint，在 package.json 中添加 next lint 脚本：

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 文件。

此后可随时运行 next lint 进行错误检查。ESLint 设置完成后，每次构建（next build）时也会自动运行。错误会导致构建失败，而警告则不会。

更多信息请参考 ESLint 插件文档。

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

Next.js 原生支持 tsconfig.json 和 jsconfig.json 文件中的 "paths" 和 "baseUrl" 选项。

这些选项允许您将项目目录映射为绝对路径，使模块导入更简洁清晰。例如：

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

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

要配置绝对导入，在 tsconfig.json 或 jsconfig.json 中添加 baseUrl 配置选项。例如：

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 位置进行解析。

On this page