Next.js 中文网

主题

安装 ​

¥Installation

创建一个新的 Next.js 应用并在本地运行。

¥Create a new Next.js app and run it locally.

快速入门 ​

¥Quick start

  1. 创建一个名为 my-app 的新 Next.js 应用。

    ¥Create a new Next.js app named my-app

  2. 运行 cd my-app 并启动开发服务器。

    ¥cd my-app and start the dev server.

  3. 访问 http://localhost:3000。

    ¥Visit http://localhost:3000.

bash
pnpm create next-app@latest my-app --yes
cd my-app
pnpm dev
bash
npx create-next-app@latest my-app --yes
cd my-app
npm run dev
bash
yarn create next-app@latest my-app --yes
cd my-app
yarn dev
bash
bun create next-app@latest my-app --yes
cd my-app
bun dev

  • --yes 使用已保存的首选项或默认值跳过提示。默认设置启用 TypeScript、Tailwind、ESLint、App Router 和 Turbopack，导入别名 @/*。

    ¥--yes skips prompts using saved preferences or defaults. The default setup enables TypeScript, Tailwind, ESLint, App Router, and Turbopack, with import alias @/*.

系统要求 ​

¥System requirements

开始之前，请确保你的开发环境满足以下要求：

¥Before you begin, make sure your development environment meets the following requirements:

  • 最低 Node.js 版本：20.9

    ¥Minimum Node.js version: 20.9

  • 操作系统：macOS、Windows（包括 WSL）和 Linux。

    ¥Operating systems: macOS, Windows (including WSL), and Linux.

支持的浏览器 ​

¥Supported browsers

Next.js 以零配置支持现代浏览器。

¥Next.js supports modern browsers with zero configuration.

  • Chrome 111+

  • Edge 111+

  • Firefox 111+

  • Safari 16.4+

了解更多关于 浏览器支持 的信息，包括如何配置 polyfill 和针对特定浏览器。

¥Learn more about browser support, including how to configure polyfills and target specific browsers.

使用 CLI 创建 ​

¥Create with the CLI

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

¥The quickest way to create a new Next.js app is using create-next-app, which sets up everything automatically for you. To create a project, run:

bash
npx create-next-app@latest

安装时，你将看到以下提示：

¥On installation, you'll see the following prompts:

txt
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，你将看到以下提示：

¥If you choose to customize settings, you'll see the following prompts:

txt
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 customize the import alias (`@/*` by default)? No / Yes
What import alias would you like configured? @/*

出现提示后，create-next-app 将以你的项目名称创建一个文件夹并安装所需的依赖。

¥After the prompts, create-next-app will create a folder with your project name and install the required dependencies.

手动安装 ​

¥Manual installation

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

¥To manually create a new Next.js app, install the required packages:

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

需要了解：App Router 使用内置的 React 预览版发布，其中包含所有稳定的 React 19 更改以及正在框架中验证的新功能。Pages Router 使用你在 package.json 中安装的 React 版本。

¥Good to know: The App Router uses React canary releases built-in, which include all the stable React 19 changes, as well as newer features being validated in frameworks. The Pages Router uses the React version you install in package.json.

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

¥Then, add the following scripts to your package.json file:

这些脚本涉及开发应用的不同阶段：

¥These scripts refer to the different stages of developing an application:

  • next dev：使用 Turbopack（默认打包工具）启动开发服务器。

    ¥next dev: Starts the development server using Turbopack (default bundler).

  • next build：构建用于生产环境的应用。

    ¥next build: Builds the application for production.

  • next start：启动生产服务器。

    ¥next start: Starts the production server.

  • eslint：运行 ESLint。

    ¥eslint: Runs ESLint.

Turbopack 现在是默认打包工具。要使用 Webpack，请运行 next dev --webpack 或 next build --webpack。请参阅 Turbopack 文档 获取配置详情。

¥Turbopack is now the default bundler. To use Webpack run next dev --webpack or next build --webpack. See the Turbopack docs for configuration details.

创建 app 目录 ​

¥Create the app directory

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

¥Next.js uses file-system routing, which means the routes in your application are determined by how you structure your files.

创建 app 文件夹。然后，在 app 内部创建一个 layout.tsx 文件。此文件为 根布局。它是必需的，并且必须包含 <html> 和 <body> 标签。

¥Create an app folder. Then, inside app, create a layout.tsx file. This file is the root layout. It's required and must contain the <html> and <body> tags.

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

创建一个包含一些初始内容的主页 app/page.tsx：

¥Create a home page app/page.tsx with some initial content:

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

当用户访问应用的根目录 (/) 时，layout.tsx 和 page.tsx 都会被渲染。

¥Both layout.tsx and page.tsx will be rendered when the user visits the root of your application (/).

需要了解：

¥Good to know:

  • 如果你忘记创建根布局，Next.js 将在使用 next dev 运行开发服务器时自动创建此文件。

    ¥If you forget to create the root layout, Next.js will automatically create this file when running the development server with next dev.

  • 你可以选择在项目的根目录中使用 src 文件夹 将应用的代码与配置文件分开。

    ¥You can optionally use a src folder in the root of your project to separate your application's code from configuration files.

创建 public 文件夹（可选） ​

¥Create the public folder (optional)

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

¥Create a public folder at the root of your project to store static assets such as images, fonts, etc. Files inside public can then be referenced by your code starting from the base URL (/).

然后，你可以使用根路径 (/) 引用这些资源。例如，public/profile.png 可以引用为 /profile.png：

¥You can then reference these assets using the root path (/). For example, public/profile.png can be referenced as /profile.png:

tsx
import Image from 'next/image'

export default function Page() {
  return <img src="https://nextjs.org/_next/image?url=https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/docs/light/typescript-command-palette.png&w=3840&q=75"/>

请参阅 [TypeScript 参考](/docs/app/api-reference/config/typescript) 页了解更多信息。

¥See the [TypeScript reference](/docs/app/api-reference/config/typescript) page for more information.

## 设置代码检查 {#set-up-linting}

¥Set up linting

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

¥Next.js supports linting with either ESLint or Biome. Choose a linter and run it directly via `package.json` scripts.

* 使用 ESLint（综合规则）：

  ¥Use **ESLint** (comprehensive rules):

* 或者使用 Biome（快速代码检查器 + 格式化器）：

  ¥Or use **Biome** (fast linter + formatter):

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

¥If your project previously used `next lint`, migrate your scripts to the ESLint CLI with the codemod:

```bash filename="Terminal"
npx @next/codemod@canary next-lint-to-eslint-cli .

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

¥If you use ESLint, create an explicit config (recommended eslint.config.mjs). ESLint supports both the legacy .eslintrc.* and the newer eslint.config.mjs formats. See the ESLint API reference for a recommended setup.

需要了解：从 Next.js 16 开始，next build 不再自动运行代码检查器。或者，你可以通过 NPM 脚本运行代码检查器。

¥Good to know: Starting with Next.js 16, next build no longer runs the linter automatically. Instead, you can run your linter through NPM scripts.

请参阅 ESLint 插件 页了解更多信息。

¥See the ESLint Plugin page for more information.

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

¥Set up Absolute Imports and Module Path Aliases

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

¥Next.js has in-built support for the "paths" and "baseUrl" options of tsconfig.json and jsconfig.json files.

这些选项允许你将项目目录别名为绝对路径，从而使导入模块更加轻松简洁。例如：

¥These options allow you to alias project directories to absolute paths, making it easier and cleaner to import modules. For example:

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

¥To configure absolute imports, add the baseUrl configuration option to your tsconfig.json or jsconfig.json file. For example:

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

¥In addition to configuring the baseUrl path, you can use the "paths" option to "alias" module paths.

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

¥For example, the following configuration maps @/components/* to components/*:

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

¥Each of the "paths" are relative to the baseUrl location.