安装与创建项目

本章带你从零搭建一个 Next.js 应用，了解系统要求、CLI 工具、手动安装流程以及 TypeScript、ESLint、路径别名等基础配置。

系统要求

Node.js 20.9 及以上。
macOS、Windows（含 WSL）或 Linux。
浏览器：Chrome 111+、Edge 111+、Firefox 111+、Safari 16.4+。

通过 CLI 快速创建

推荐使用官方脚手架 create-next-app，一键生成带最佳实践的项目：

pnpm create next-app@latest my-app --yes
cd my-app
pnpm dev

--yes 会跳过提示，使用默认配置：TypeScript + Tailwind CSS + ESLint + App Router + Turbopack，并自动设置 @/* 路径别名。

去掉 --yes 则会出现交互提示：

Would you like to use TypeScript? Yes
Which linter would you like to use? ESLint / Biome / None
Would you like to use React Compiler? No
Would you like to use Tailwind CSS? Yes
Would you like your code inside a `src/` directory? No
Would you like to use App Router? Yes
Would you like to customize the import alias? No

手动安装

如果你想对项目有完全掌控，也可以手动初始化：

npm i next@latest react@latest react-dom@latest

然后在 package.json 写入 scripts：

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint"
  }
}

Turbopack 已成为默认打包器。如需使用 Webpack 可运行 next dev --webpack。

创建 `app` 目录

Next.js 使用文件系统路由。在根目录新建 app/，并创建 根布局（必须包含 html 与 body）：

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="zh-CN">
      <body>{children}</body>
    </html>
  );
}

再创建首页：

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

启动 npm run dev，访问 http://localhost:3000 即可看到效果。

静态资源目录

在项目根新建 public/ 用于存放图片、字体等静态资源，文件可直接以 / 根路径访问：

import Image from 'next/image';

<Image src="/profile.png" alt="Profile" width={100} height={100} />;

TypeScript 与路径别名

Next.js 原生支持 TypeScript，只需将文件改为 .ts / .tsx，再运行 next dev，它会自动写入 tsconfig.json。

在 tsconfig.json 或 jsconfig.json 中可配置绝对引用，避免冗长的相对路径：

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

从此就可以写 import { Button } from '@/components/button'，而不是 ../../../components/button。

安裝與建立專案

本章帶你從零搭建一個 Next.js 應用，了解系統要求、CLI 工具、手動安裝流程，以及 TypeScript、ESLint、路徑別名等基礎配置。

系統要求

Node.js 20.9 及以上。
macOS、Windows（含 WSL）或 Linux。
瀏覽器：Chrome 111+、Edge 111+、Firefox 111+、Safari 16.4+。

用 CLI 快速建立

建議使用官方腳手架 create-next-app，一鍵生成帶最佳實踐的專案：

pnpm create next-app@latest my-app --yes
cd my-app
pnpm dev

--yes 會略過提示，使用預設配置：TypeScript + Tailwind CSS + ESLint + App Router + Turbopack，並自動設定 @/* 路徑別名。

去掉 --yes 則會出現互動提示：

Would you like to use TypeScript? Yes
Which linter would you like to use? ESLint / Biome / None
Would you like to use React Compiler? No
Would you like to use Tailwind CSS? Yes
Would you like your code inside a `src/` directory? No
Would you like to use App Router? Yes
Would you like to customize the import alias? No

手動安裝

如果你想對專案有完全掌控，也可以手動初始化：

npm i next@latest react@latest react-dom@latest

然後在 package.json 寫入 scripts：

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint"
  }
}

Turbopack 已成為預設打包工具。如需使用 Webpack 可執行 next dev --webpack。

建立 `app` 目錄

Next.js 採用檔案系統路由。在根目錄新建 app/，並建立 根佈局（必須包含 html 與 body）：

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="zh-HK">
      <body>{children}</body>
    </html>
  );
}

再建立首頁：

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

執行 npm run dev，瀏覽 http://localhost:3000 即可看到結果。

靜態資源目錄

在專案根新建 public/ 用於放置圖片、字型等靜態資源，檔案可直接以 / 根路徑存取：

import Image from 'next/image';

<Image src="/profile.png" alt="Profile" width={100} height={100} />;

TypeScript 與路徑別名

Next.js 原生支援 TypeScript，只需將檔案改為 .ts / .tsx，再執行 next dev，便會自動寫入 tsconfig.json。

在 tsconfig.json 或 jsconfig.json 中可設定絕對引用，避免冗長的相對路徑：

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

從此可以寫 import { Button } from '@/components/button'，不再需要 ../../../components/button。

Installation

This chapter walks you through bootstrapping a Next.js app from scratch: system requirements, the CLI, manual setup, and baseline configuration for TypeScript, ESLint, and path aliases.

System requirements

Node.js 20.9 or higher.
macOS, Windows (including WSL), or Linux.
Browsers: Chrome 111+, Edge 111+, Firefox 111+, Safari 16.4+.

Create with the CLI

The quickest path is the official scaffold create-next-app:

pnpm create next-app@latest my-app --yes
cd my-app
pnpm dev

--yes skips every prompt and uses the recommended defaults: TypeScript + Tailwind CSS + ESLint + App Router + Turbopack, with the @/* import alias wired in.

Drop --yes to see the full interactive prompts:

Would you like to use TypeScript? Yes
Which linter would you like to use? ESLint / Biome / None
Would you like to use React Compiler? No
Would you like to use Tailwind CSS? Yes
Would you like your code inside a `src/` directory? No
Would you like to use App Router? Yes
Would you like to customize the import alias? No

Manual install

For full control, install the packages yourself:

npm i next@latest react@latest react-dom@latest

Then add the scripts to package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint"
  }
}

Turbopack is the default bundler. Pass --webpack to next dev or next build to fall back to webpack.

Create the `app` directory

Next.js uses file-system routing. Create an app/ folder in the project root, and add a root layout — it's required and must contain html and body tags:

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

Then add a home page:

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

Run npm run dev and open http://localhost:3000 — your first page is live.

The `public` folder

Put static assets (images, fonts, etc.) under public/. Files inside are served from the root URL:

import Image from 'next/image';

<Image src="/profile.png" alt="Profile" width={100} height={100} />;

TypeScript and path aliases

Next.js has built-in TypeScript support: rename a file to .ts / .tsx and run next dev — it auto-generates tsconfig.json with recommended settings.

Path aliases in tsconfig.json (or jsconfig.json) keep imports tidy:

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

You can then write import { Button } from '@/components/button' instead of ../../../components/button.

Previous ChapterIntroduction to Next.js

Next ChapterApp Router