跳到内容

创建一个新的 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。

创建 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 中的文件。

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

运行开发服务器

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

设置 TypeScript

最低 TypeScript 版本:v4.5.2

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

有关更多信息,请参阅 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 配置以及更严格的核心 Web 指标规则集。对于首次设置 ESLint 的开发人员,这是推荐的配置。
  • 基本:包括 Next.js 的基本 ESLint 配置。
  • 取消:跳过配置。如果您计划设置自己的自定义 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'

要配置绝对导入,请将 baseUrl 配置选项添加到您的 tsconfig.jsonjsconfig.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 位置。