Menu

创建一个 Next.js 项目

系统要求：

  • Node.js 18.18 或更高版本。
  • 支持 macOS、Windows (包括 WSL) 和 Linux。

自动安装

我们建议使用 create-next-app 来启动一个新的 Next.js 应用程序，它会为你自动设置好一切。要创建一个项目，请运行：

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 新手，请查看 项目结构 文档，了解应用程序中所有可能的文件和文件夹的概览。

值得注意的是：

手动安装

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

Terminal
npm install next@latest react@latest react-dom@latest

打开你的 package.json 文件，添加以下 scripts：

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

这些脚本对应用程序开发的不同阶段：

  • dev：运行 next dev 以开发模式启动 Next.js。
  • build：运行 next build 以构建用于生产的应用程序。
  • start：运行 next start 以启动 Next.js 生产服务器。
  • lint：运行 next lint 以设置 Next.js 的内置 ESLint 配置。

创建 app 目录

Next.js 使用文件系统路由，这意味着应用程序中的路由是由文件结构决定的。

创建一个 app 文件夹，然后添加 layout.tsx 和 page.tsx 文件。当用户访问应用程序的根目录（/）时，这些文件将被渲染。

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.tsx，Next.js 在运行开发服务器（使用 next dev）时会自动创建这个文件。
  • 你可以选择在项目根目录使用 src 目录，将应用程序代码与配置文件分开。

创建 public 文件夹（可选）

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

运行开发服务器

  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 命令面板

现在，编辑文件时，自定义插件将被启用。运行 next build 时，将使用自定义类型检查器。

查看 TypeScript 配置页面，了解有关如何在项目中使用 TypeScript 的更多信息。

设置 ESLint

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

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

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

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

Terminal
npm 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 配置。仅在你计划设置自己的自定义 ESLint 配置时选择此选项。

如果选择了前两种配置选项中的任何一种，Next.js 将自动在你的应用程序中安装 eslint 和 eslint-config-next 作为依赖项，并在项目根目录创建一个包含所选配置的 .eslintrc.json 文件。

现在，每次想要运行 ESLint 来捕获错误时，你都可以运行 next lint。一旦设置了 ESLint，它也会在每次构建（next build）期间自动运行。错误将导致构建失败，而警告则不会。

查看 ESLint 插件页面，了解有关如何在项目中配置 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
{
  "compilerOptions": {
    "baseUrl": "src/"
  }
}

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

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

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

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

src/app/page.tsx
TypeScript
import Button from '@/components/button'
import '@/styles/styles.css'
 
export default function HomePage() {
  return (
    <div>
      <h1>Hello World</h1>
      <Button />
    </div>
  )
}