Menu

创建新的 Next.js 应用

系统要求

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

  • Node.js 20.9 或更高版本。
  • macOS、Windows（包括 WSL）或 Linux。

使用 CLI 创建

创建新 Next.js 应用程序最快的方法是使用 create-next-app，它会为你自动设置所有内容。要创建项目，请运行：

Terminal
npx create-next-app@latest

在安装过程中，你将看到以下提示：

Terminal
What is your project named? my-app
Would you like to use the recommended Next.js defaults?
    Yes, use recommended defaults - TypeScript, ESLint, Tailwind CSS, App Router, Turbopack
    No, reuse previous settings
    No, customize settings - Choose your own preferences

如果你选择 customize settings，你将看到以下提示：

Terminal
Would you like to use TypeScript? No / Yes
Which linter would you like to use? ESLint / Biome / None
Would you like to use React Compiler? 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? (recommended) 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 应用程序，请安装所需的包：

pnpm i next@latest react@latest react-dom@latest
npm i next@latest react@latest react-dom@latest
yarn add next@latest react@latest react-dom@latest
bun add next@latest react@latest react-dom@latest

值得注意的是：App Router 使用内置的 React canary 版本，其中包含所有稳定的 React 19 更改，以及正在框架中验证的更新功能。Pages Router 使用你在 package.json 中安装的 React 版本。

然后，将以下脚本添加到你的 package.json 文件中：

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

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

  • next dev：使用 Turbopack（默认打包工具）启动开发服务器。
  • next build：为生产环境构建应用程序。
  • next start：启动生产服务器。
  • eslint：运行 ESLint。

Turbopack 现在是默认的打包工具。要使用 Webpack，请运行 next dev --webpack 或 next build --webpack。有关配置详细信息，请参阅 Turbopack 文档。

创建 pages 目录

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

在项目根目录创建一个 pages 目录。然后，在 pages 文件夹中添加一个 index.tsx 文件。这将是你的主页（/）：

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

接下来，在 pages/ 中添加一个 _app.tsx 文件来定义全局布局。了解更多关于自定义 App 文件的信息。

pages/_app.tsx
TypeScript
import type { AppProps } from 'next/app'
 
export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

最后，在 pages/ 中添加一个 _document.tsx 文件来控制服务器的初始响应。了解更多关于自定义 Document 文件的信息。

pages/_document.tsx
TypeScript
import { Html, Head, Main, NextScript } from 'next/document'
 
export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

创建 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. 编辑 pages/index.tsx 文件并保存，在浏览器中查看更新后的结果。

设置 TypeScript

最低 TypeScript 版本：v5.1.0

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

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

设置代码检查

Next.js 支持使用 ESLint 或 Biome 进行代码检查。选择一个代码检查工具，并通过 package.json 脚本直接运行它。

  • 使用 ESLint（全面的规则）：
package.json
{
  "scripts": {
    "lint": "eslint",
    "lint:fix": "eslint --fix"
  }
}
  • 或使用 Biome（快速的代码检查工具 + 格式化工具）：
package.json
{
  "scripts": {
    "lint": "biome check",
    "format": "biome format --write"
  }
}

如果你的项目之前使用 next lint，请使用 codemod 将脚本迁移到 ESLint CLI：

Terminal
npx @next/codemod@canary next-lint-to-eslint-cli .

如果你使用 ESLint，请创建一个显式配置（推荐使用 eslint.config.mjs）。ESLint 支持旧版 .eslintrc.* 和较新的 eslint.config.mjs 格式。有关推荐设置，请参阅 ESLint API 参考。

值得注意的是：从 Next.js 16 开始，next build 不再自动运行代码检查工具。相反，你可以通过 NPM 脚本运行代码检查工具。

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

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

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

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

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

要配置绝对导入，请将 baseUrl 配置选项添加到你的 tsconfig.json 或 jsconfig.json 文件中。例如：

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

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

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

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

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