创建一个新的 Next.js 应用程序

系统要求

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

自动安装

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

终端

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 文件，并添加以下 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 配置。

创建 `pages` 目录

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

在你的项目根目录创建一个 pages 目录。然后，在你的 pages 文件夹中添加一个 index.tsx 文件。这将成为你的主页 (/)

pages/index.tsx

export default function Page() {
  return <h1>Hello, 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 文件夹，用于存储静态资源，例如图像、字体等。然后，可以从根 URL (/) 开始，通过代码引用 public 文件夹中的文件。

运行开发服务器

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

设置 TypeScript

最低 TypeScript 版本：v4.5.2

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

请参阅 TypeScript 配置页面，了解有关如何在你的项目中使用 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 配置。仅当你计划设置自己的自定义 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" 选项。这些选项允许你将项目目录别名为绝对路径，从而更轻松地导入模块。例如

// 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" 选项来 "别名" 模块路径。

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

tsconfig.json 或 jsconfig.json

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

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

src/app/page.tsx

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