安装 | DevRefinery | DevRefinery

App Router Only

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

快速开始

创建一个名为 my-app 的新 Next.js 应用
cd my-app 并启动开发服务器。
访问 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，导入别名为 @/*。

系统要求

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

最低 Node.js 版本：20.9
操作系统：macOS、Windows（包括 WSL）和 Linux。

支持的浏览器

Next.js 支持现代浏览器，无需配置。

Chrome 111+
Edge 111+
Firefox 111+
Safari 16.4+

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

使用 CLI 创建

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

bash

npx create-next-app@latest

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

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

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 将创建一个以你的项目名称命名的文件夹并安装所需的依赖项。

手动安装

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

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 canary 版本，包括所有稳定的 React 19 更改，以及正在框架中验证的新功能。Pages Router 使用你在 package.json 中安装的 React 版本。

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

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 文档。

App Router Only

创建 `app` 目录

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

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

tsx

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

jsx

export default function RootLayout({ children }) {
    return (
        <html lang="en">
            <body>{children}</body>
        </html>
    );
}

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

tsx

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

jsx

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

当用户访问应用程序的根路径（/）时，layout.tsx 和 page.tsx 都会被渲染。

提示：

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

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

Pages Router Only

创建 `pages` 目录

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

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

tsx

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

jsx

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

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

tsx

import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
    return <Component {...pageProps} />;
}

jsx

export default function App({ Component, pageProps }) {
    return <Component {...pageProps} />;
}

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

tsx

import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
    return (
        <Html>
            <Head />
            <body>
                <Main />
                <NextScript />
            </body>
        </Html>
    );
}

jsx

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：

tsx

import Image from "next/image";

export default function Page() {
    return <Image src="/profile.png" alt="Profile" width={100} height={100} />;
}

jsx

import Image from "next/image";

export default function Page() {
    return <Image src="/profile.png" alt="Profile" width={100} height={100} />;
}

运行开发服务器

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

设置 TypeScript

最低 TypeScript 版本：v5.1.0

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

App Router Only

IDE 插件

Next.js 包含一个自定义 TypeScript 插件和类型检查器，VSCode 和其他代码编辑器可以使用它进行高级类型检查和自动完成。

你可以通过以下方式在 VS Code 中启用插件：

打开命令面板（Ctrl/⌘ + Shift + P）
搜索 "TypeScript: Select TypeScript Version"
选择 "Use Workspace Version"

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

设置代码检查

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

使用 ESLint（全面的规则）：

json

{
    "scripts": {
        "lint": "eslint",
        "lint:fix": "eslint --fix"
    }
}

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

json

{
    "scripts": {
        "lint": "biome check",
        "format": "biome format --write"
    }
}

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

bash

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" 选项。

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

jsx

// Before
import { Button } from "../../../components/button";

// After
import { Button } from "@/components/button";

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

json

{
    "compilerOptions": {
        "baseUrl": "src/"
    }
}

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

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

json

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

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

App Router Only

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

快速开始

创建一个名为 my-app 的新 Next.js 应用
cd my-app 并启动开发服务器。
访问 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，导入别名为 @/*。

系统要求

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

最低 Node.js 版本：20.9
操作系统：macOS、Windows（包括 WSL）和 Linux。

支持的浏览器

Next.js 支持现代浏览器，无需配置。

Chrome 111+
Edge 111+
Firefox 111+
Safari 16.4+

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

使用 CLI 创建

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

bash

npx create-next-app@latest

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

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

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 将创建一个以你的项目名称命名的文件夹并安装所需的依赖项。

手动安装

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

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 canary 版本，包括所有稳定的 React 19 更改，以及正在框架中验证的新功能。Pages Router 使用你在 package.json 中安装的 React 版本。

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

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 文档。

App Router Only

创建 `app` 目录

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

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

tsx

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

jsx

export default function RootLayout({ children }) {
    return (
        <html lang="en">
            <body>{children}</body>
        </html>
    );
}

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

tsx

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

jsx

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

当用户访问应用程序的根路径（/）时，layout.tsx 和 page.tsx 都会被渲染。

提示：

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

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

Pages Router Only

创建 `pages` 目录

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

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

tsx

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

jsx

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

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

tsx

import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
    return <Component {...pageProps} />;
}

jsx

export default function App({ Component, pageProps }) {
    return <Component {...pageProps} />;
}

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

tsx

import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
    return (
        <Html>
            <Head />
            <body>
                <Main />
                <NextScript />
            </body>
        </Html>
    );
}

jsx

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：

tsx

import Image from "next/image";

export default function Page() {
    return <Image src="/profile.png" alt="Profile" width={100} height={100} />;
}

jsx

import Image from "next/image";

export default function Page() {
    return <Image src="/profile.png" alt="Profile" width={100} height={100} />;
}

运行开发服务器

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

设置 TypeScript

最低 TypeScript 版本：v5.1.0

App Router Only

IDE 插件

Next.js 包含一个自定义 TypeScript 插件和类型检查器，VSCode 和其他代码编辑器可以使用它进行高级类型检查和自动完成。

你可以通过以下方式在 VS Code 中启用插件：

打开命令面板（Ctrl/⌘ + Shift + P）
搜索 "TypeScript: Select TypeScript Version"
选择 "Use Workspace Version"

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

设置代码检查

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

使用 ESLint（全面的规则）：

json

{
    "scripts": {
        "lint": "eslint",
        "lint:fix": "eslint --fix"
    }
}

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

json

{
    "scripts": {
        "lint": "biome check",
        "format": "biome format --write"
    }
}

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

bash

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

提示：从 Next.js 16 开始，next build 不再自动运行代码检查器。相反，你可以通过 NPM 脚本运行代码检查器。

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

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

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

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

jsx

// Before
import { Button } from "../../../components/button";

// After
import { Button } from "@/components/button";

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

json

{
    "compilerOptions": {
        "baseUrl": "src/"
    }
}

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

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

json

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

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

文档导航

快速开始

系统要求

支持的浏览器

使用 CLI 创建

手动安装

创建 app 目录

创建 pages 目录

创建 public 文件夹（可选）

运行开发服务器

设置 TypeScript

IDE 插件

设置代码检查

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

快速开始

系统要求

支持的浏览器

使用 CLI 创建

手动安装

创建 app 目录

创建 pages 目录

创建 public 文件夹（可选）

运行开发服务器

设置 TypeScript

IDE 插件

设置代码检查

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

创建 `app` 目录

创建 `pages` 目录

创建 `public` 文件夹（可选）

创建 `app` 目录

创建 `pages` 目录

创建 `public` 文件夹（可选）