安装指南

系统要求：

Node.js 16.14 或更高版本
支持 macOS、Windows（包括 WSL）和 Linux 系统

自动安装

推荐使用 create-next-app 创建新项目，该工具会自动完成所有初始化配置。执行以下命令创建项目：

终端

npx create-next-app@latest

安装过程中会看到以下选项提示：

终端

请输入项目名称？my-app
是否使用 TypeScript？否 / 是
是否使用 ESLint？否 / 是
是否使用 Tailwind CSS？否 / 是
是否使用 `src/` 目录？否 / 是
是否使用 App Router？（推荐）否 / 是
是否自定义默认导入别名 (@/*)？否 / 是
请输入需要配置的导入别名？@/*

完成选择后，create-next-app 会创建项目文件夹并安装所需依赖。

须知：

Next.js 现已默认集成 TypeScript、ESLint 和 Tailwind CSS 配置

可选择使用 src 目录将应用代码与配置文件分离

手动安装

手动创建 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"
  }
}

这些脚本对应不同的开发阶段：

dev: 执行 next dev 启动开发模式
build: 执行 next build 构建生产环境应用
start: 执行 next start 启动生产服务器
lint: 执行 next lint 配置内置 ESLint

创建目录结构

Next.js 采用文件系统路由，应用路由由文件结构决定。

`app` 目录（推荐）

新项目建议使用 App Router。该路由支持 React 最新特性，是根据社区反馈对 Pages Router 的演进。

创建 app/ 目录后，需添加 layout.tsx 和 page.tsx 文件，这些文件会在用户访问根路径 (/) 时渲染。

在 app/layout.tsx 中创建包含必需 <html> 和 <body> 标签的根布局：

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

最后在 app/page.tsx 创建首页内容：

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

须知：如果忘记创建 layout.tsx，执行 next dev 启动开发服务器时 Next.js 会自动生成该文件。

了解更多关于 App Router 的使用。

`pages` 目录（可选）

如需使用 Pages Router 而非 App Router，可在项目根目录创建 pages/ 文件夹。

然后在 pages 目录中添加 index.tsx 作为首页 (/)：

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

接着在 pages/ 下创建 _app.tsx 定义全局布局，详见自定义 App 文件。

import type { AppProps } from 'next/app'

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

最后添加 _document.tsx 控制服务端初始响应，详见自定义 Document 文件。

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

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

了解更多关于 Pages Router 的使用。

须知：虽然可以在同一项目中同时使用两种路由，但 app 目录下的路由优先级高于 pages。建议新项目只使用一种路由以避免混淆。

`public` 目录（可选）

创建 public 文件夹存放图片、字体等静态资源，这些文件可通过根路径 (/) 直接引用。

启动开发服务器

执行 npm run dev 启动开发服务器
访问 http://localhost:3000 查看应用
修改 app/layout.tsx（或 pages/index.tsx）文件并保存，浏览器会自动更新变化

自动安装

手动安装

创建目录结构

app 目录（推荐）

pages 目录（可选）

public 目录（可选）

启动开发服务器

On this page

`app` 目录（推荐）

`pages` 目录（可选）

`public` 目录（可选）