第一章：环境搭建 - Next.js 速成教程

1. 环境要求

Next.js 15 需要较新的 Node.js 运行时。安装前请确认本机环境满足版本要求。

Node.js：18.17 及以上（官方最低要求）；推荐使用 20.x LTS，长期支持且与生态工具兼容性好。

在终端中验证是否已正确安装：

node -v
npm -v

包管理器任选其一即可：

npm：随 Node 自带，零配置。
pnpm：推荐，硬链接与内容寻址存储，安装快、磁盘占用小。
yarn：经典选择，与多数 CI 文档兼容。

💡 建议

团队新项目可优先采用 pnpm：依赖解析速度快，且全局 store 能显著节省磁盘空间。安装方式见 pnpm 官方文档。

2. 创建 Next.js 项目

使用官方脚手架 create-next-app 一键初始化项目：

npx create-next-app@latest my-app

执行后会进入交互式向导，与本教程一致的推荐选项如下：

TypeScript：Yes —— 类型安全，与 Next 15 生态默认一致。
ESLint：Yes —— 统一代码风格。
Tailwind CSS：Yes —— 实用优先的样式方案，与本站教程样式一致。
src/ directory：Yes —— 将应用代码集中在 src/ 下，结构更清晰。
App Router：Yes —— 使用 app/ 目录（Next 13+ 推荐）。
Import alias：@/* —— 用 @/components/foo 代替深层相对路径。

若希望非交互、一次性指定相同选项，可使用等价命令：

npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"

💡 要点

Next.js 15 默认以 App Router（app/）为主，这是当前官方推荐的路由与布局方案；旧版 Pages Router（pages/）仍可选用，新项目建议直接 App Router。

3. 项目目录结构

勾选 src/ 与 App Router 后，典型目录如下（文件名可能随模板微调）：

my-app/
├── src/
│   └── app/
│       ├── layout.tsx      # 根布局
│       ├── page.tsx        # 首页
│       ├── globals.css     # 全局样式
│       └── favicon.ico
├── public/                 # 静态资源
├── next.config.ts          # Next.js 配置
├── tsconfig.json           # TypeScript 配置
├── tailwind.config.ts      # Tailwind 配置
├── package.json
└── .eslintrc.json

layout.tsx：根布局，包裹当前路由段及其子路由的 UI，可嵌套；常用于 html/body、字体、全局 Provider。
page.tsx：路由页面组件，对应 URL 的可渲染内容；与 layout.tsx 组合构成完整页面。
next.config.ts：Next.js 构建与运行时行为的配置入口（压缩、图片域、重定向等）。

layout.tsx 示例

根布局导出 metadata 与包裹 children 的根结构：

import type { Metadata } from "next";
import "./globals.css";

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

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

page.tsx 示例

首页默认导出 React 组件，即路由 / 的 UI：

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1 className="text-4xl font-bold">Welcome to Next.js</h1>
      <p className="mt-4 text-gray-600">编辑 src/app/page.tsx 开始开发。</p>
    </main>
  );
}

4. 开发命令

进入项目目录后，常用脚本定义在 package.json 的 scripts 中。若使用 pnpm / yarn，将下表中的 npm 替换为对应命令即可。

命令	作用
npm run dev	启动开发服务器，默认 `http://localhost:3000`，支持 Fast Refresh。
npm run build	构建生产优化产物（输出到 `.next`）。
npm run start	在已构建的前提下启动生产模式 Node 服务器（需先 `build`）。
npm run lint	运行 ESLint，检查代码规范与常见错误。

5. next.config.ts 基本配置

Next.js 15 推荐使用 TypeScript 配置文件。下面是一份包含常见选项的起步示例（可按项目删减）：

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  reactStrictMode: true,
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "example.com",
        pathname: "/images/**",
      },
    ],
  },
  // 按需启用实验特性；具体项以官方文档为准
  // experimental: { ... },
};

export default nextConfig;

reactStrictMode：在开发模式下启用 React 严格模式，有助于发现副作用问题；生产构建行为以 React 文档为准。
images.remotePatterns：使用 next/image 加载外部域名图片时，必须在此声明允许的协议、主机与路径模式（安全白名单）。
experimental：实验性 API 的开关；升级小版本前请查阅 next.config.js 文档，避免依赖未稳定特性。

6. VS Code 推荐配置

有 React 基础的开发者可安装以下扩展，提升日常开发效率：

ES7+ React/Redux/React-Native snippets：快速插入函数组件、hooks 等片段。
Tailwind CSS IntelliSense：类名自动补全与预览（与 Tailwind 模板配合）。
ESLint：与项目内 ESLint 规则联动，保存时提示问题。
Prettier：统一格式化；建议与 ESLint 通过 eslint-config-prettier 避免规则冲突。

与 Vite + React 对比

Next.js 开箱即用提供服务端渲染（SSR）、静态生成（SSG）、基于文件系统的 App Router、以及同仓库内的 Route Handlers（原 API 路由能力）等；而典型的 Vite + React 脚手架更偏 SPA，上述能力往往需要自行选型并拼接插件与服务器。若你的目标是全栈或 SEO 友好的站点，Next 的默认形态更省心。

7. 本章要点

环境与工具链

确认 Node 18.17+（推荐 20 LTS），用 node -v / npm -v 自检；包管理器可选 npm / pnpm / yarn。

项目创建

使用 create-next-app@latest，开启 TypeScript、ESLint、Tailwind、src/、App Router 与 @/* 别名。

目录与入口

理解 app/layout.tsx（根布局）与 app/page.tsx（页面），静态资源放 public/。

脚本与配置

掌握 dev / build / start / lint；在 next.config.ts 中按需配置严格模式与图片远程域等。