第 1 课：Hello Next.js — 从零搭建你的第一个应用

王小酱
1 阅读8分钟

模块一：破冰入门 | 前置要求：React 基础（JSX、组件、props、state） 覆盖文档：Installation、Local Development 时长：90 分钟

一、Next.js 是什么

1.1 定位

Next.js 是一个基于 React 的全栈 Web 框架，由 Vercel 开发维护。它不仅仅是一个路由库或 SSR 方案——它提供了从开发到部署的完整解决方案。

与其他方案的区别：

特性CRA (Create React App)Vite + ReactNext.js
服务端渲染 (SSR)不支持需手动配置内置
静态生成 (SSG)不支持需手动配置内置
增量静态再生 (ISR)不支持不支持内置
流式渲染 (Streaming)不支持不支持内置
文件系统路由不支持不支持内置
API 路由不支持不支持内置
图片/字体优化不支持不支持内置
全栈能力仅前端仅前端前端 + 后端

1.2 核心理念

Next.js 16 的核心理念是组件级的静态/动态光谱：

  • 传统框架：一个页面要么是静态的，要么是动态的（路由级二选一）
  • Next.js：同一个页面可以混合静态和动态内容（组件级粒度）

这意味着一个页面的导航栏可以是静态的（构建时生成），产品列表可以是缓存的（定时刷新），而用户偏好可以是动态的（每次请求获取）——全部在一个流式响应中交付。

1.3 两套路由系统

Next.js 目前有两套路由系统：

  • App Router（推荐，本课程主线）：基于 app/ 目录，支持 React Server Components、Streaming、Server Actions
  • Pages Router（传统）：基于 pages/ 目录，使用 getStaticProps/getServerSideProps

本课程以 App Router 为主线，第 34-35 课会详细讲解 Pages Router 及迁移。

二、环境准备

2.1 系统要求

  • Node.js：版本 20.9 或更高
  • 操作系统：macOS、Windows（包括 WSL）、Linux
  • 包管理器：推荐 pnpm（也支持 npm、yarn、bun）

检查 Node.js 版本：

node -v
# 需要 v20.9.0 或更高

安装 pnpm（如果没有）：

npm install -g pnpm

2.2 浏览器支持

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

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

如果需要支持更旧的浏览器，可以通过 Browserslist 配置 polyfills（详见第 18 课 next.config.ts）。

2.3 IDE 配置

推荐使用 VS Code，并启用 Next.js TypeScript 插件：

  1. 打开 VS Code 命令面板：Ctrl/Cmd + Shift + P
  2. 搜索 "TypeScript: Select TypeScript Version"
  3. 选择 "Use Workspace Version"

这样可以获得 Next.js 特有的类型检查和自动补全。

三、创建项目

3.1 使用 create-next-app（推荐）

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

--yes 标志使用推荐默认配置，包含：

  • TypeScript
  • Tailwind CSS
  • ESLint
  • App Router
  • Turbopack（默认 bundler）
  • 路径别名 @/*
  • AGENTS.md（引导 AI 编程 Agent）

访问 http://localhost:3000 即可看到应用。

3.2 交互式创建

如果不使用 --yes，会看到以下提示：

What is your project named? my-app
Would you like to use the recommended Next.js defaults?
    Yes, use recommended defaults
    No, reuse previous settings
    No, customize settings

选择 "customize settings" 后可以逐项配置：

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? → 取决于团队习惯
Would you like to use App Router? (recommended) → Yes
Would you like to customize the import alias? → Yes, @/*
Would you like to include AGENTS.md? → Yes

3.3 手动安装

如果你想在已有项目中添加 Next.js：

pnpm i next@latest react@latest react-dom@latest

然后在 package.json 中添加脚本：

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

创建 app/layout.tsx（根布局，必需）：

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

创建 app/page.tsx（首页）：

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

注意：如果忘记创建根布局，运行 next dev 时 Next.js 会自动创建。

四、项目脚本详解

4.1 开发服务器

pnpm dev
# 等同于 next dev
  • 启动开发服务器（默认端口 3000）
  • 使用 Turbopack 作为默认 bundler（比 Webpack 快得多）
  • 支持 Fast Refresh（修改文件后即时更新，保持组件状态）
  • 如果要使用 Webpack：pnpm dev -- --webpack

4.2 生产构建

pnpm build
# 等同于 next build
  • 编译应用为生产优化版本
  • 生成 .next/ 目录
  • 执行静态生成、代码分割、Tree Shaking、压缩
  • 注意：Next.js 16 起 next build 不再自动运行 linter

4.3 生产服务器

pnpm start
# 等同于 next start
  • 启动 Node.js 生产服务器
  • 必须先运行 pnpm build
  • 默认端口 3000，可用 -p 指定：pnpm start -- -p 8080

4.4 代码检查

pnpm lint        # 运行 ESLint
pnpm lint:fix    # 自动修复

五、Turbopack vs Webpack

5.1 Turbopack 简介

Turbopack 是 Next.js 团队用 Rust 编写的新一代 bundler，现在是 next dev 和 next build 的默认 bundler。

优势：

  • 增量编译速度极快（文件变更后 1-2 秒）
  • 基于 Rust，内存效率高
  • 与 Next.js 深度集成

5.2 切换到 Webpack

如果你的项目有 Turbopack 不支持的 Webpack 插件：

next dev --webpack      # 开发时用 Webpack
next build --webpack    # 构建时用 Webpack

注意：没有 --no-turbopack 标志。

5.3 如何选择

场景推荐
新项目Turbopack（默认）
依赖特殊 Webpack 插件Webpack
需要自定义 Webpack 配置Webpack（Turbopack 有自己的配置方式）

六、开发工具链配置

6.1 ESLint 配置

Next.js 推荐使用 ESLint。创建 eslint.config.mjs：

// eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.extends('next/core-web-vitals', 'next/typescript'),
]

export default eslintConfig

6.2 Biome（替代方案）

Biome 是一个快速的 linter + formatter，作为 ESLint + Prettier 的替代：

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

选择建议：

  • ESLint：社区生态丰富、规则多、Next.js 官方支持
  • Biome：速度快、配置简单、集成 formatter

6.3 TypeScript 配置

Next.js 内置 TypeScript 支持。项目创建后自动生成 tsconfig.json。

要添加 TypeScript 到已有项目，只需将文件扩展名从 .js 改为 .ts/.tsx，运行 next dev 后 Next.js 会自动安装所需依赖并生成 tsconfig.json。

七、路径别名

7.1 配置别名

Next.js 内置支持 tsconfig.json 的 paths 和 baseUrl。

默认配置（@/* 映射到根目录）：

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

如果使用 src/ 目录：

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

7.2 使用别名

// 之前：相对路径
import { Button } from '../../../components/button'

// 之后：路径别名
import { Button } from '@/components/button'

八、App Router 与 React Canary

8.1 为什么用 React Canary

App Router 使用 React canary 版本，包含：

  • 所有稳定的 React 19 更改
  • 正在框架中验证的新特性（如 Server Components、Server Actions）

你仍然需要在 package.json 中声明 react 和 react-dom，用于工具链和生态兼容。

8.2 AGENTS.md

Next.js 16.3+ 支持在项目中包含 AGENTS.md 文件（指向 CLAUDE.md），引导 AI 编程 Agent（如 Claude、Cursor、GitHub Copilot）使用与项目版本匹配的文档，而非可能过时的训练数据。

文档捆绑在 node_modules/next/dist/docs/，在 next dev 时自动生成。可通过 next.config.ts 中 agentRules: false 禁用。

九、项目结构初探

创建项目后，你会看到以下结构：

my-app/
├── app/
│   ├── layout.tsx        ← 根布局（必需）
│   ├── page.tsx          ← 首页
│   ├── favicon.ico       ← 网站图标
│   └── globals.css       ← 全局样式
├── public/               ← 静态资源
│   ├── file.svg
│   └── ...
├── .gitignore
├── eslint.config.mjs     ← ESLint 配置
├── next.config.ts        ← Next.js 配置
├── package.json
├── postcss.config.mjs    ← PostCSS（Tailwind 需要）
├── tailwind.config.ts    ← Tailwind 配置（如有）
├── tsconfig.json         ← TypeScript 配置
└── AGENTS.md             ← AI Agent 引导文件

关键目录说明：

  • app/：路由和页面代码（核心目录）
  • public/：静态资源（图片、字体等），直接映射到 / 路径
  • .next/：构建产物（自动生成，不应提交到 Git）

十、Fast Refresh 体验

10.1 什么是 Fast Refresh

Fast Refresh 是 Next.js 的热更新机制：

  • 修改文件后 即时 更新浏览器
  • 保持组件状态（不像全页刷新那样丢失状态）
  • 语法错误修复后自动恢复

10.2 动手体验

  1. 启动开发服务器：pnpm dev
  2. 打开 http://localhost:3000
  3. 修改 app/page.tsx：
// app/page.tsx
export default function Page() {
  return (
    <div>
      <h1>Hello, Next.js!</h1>
      <p>这是我的第一个 Next.js 应用</p>
    </div>
  )
}
  1. 保存文件，观察浏览器即时更新

十一、本地开发优化建议

11.1 杀毒软件排除

在 macOS/Windows 上，杀毒软件扫描 node_modules/ 和 .next/ 目录会显著拖慢开发体验。建议将项目目录添加到杀毒软件的排除列表。

11.2 端口占用

默认端口 3000 被占用时，Next.js 会自动尝试下一个可用端口。也可以手动指定：

pnpm dev -- -p 4000

11.3 HTTPS 开发

需要 HTTPS 时（例如测试 Service Worker）：

pnpm dev -- --experimental-https

Next.js 会自动生成自签名证书。

十二、课后练习

练习 1：创建项目（基础）

  1. 使用 pnpm create next-app@latest 创建项目
  2. 启动开发服务器并访问 http://localhost:3000
  3. 修改 app/page.tsx 的内容，观察 Fast Refresh

练习 2：路径别名（中阶）

  1. 在项目中创建 lib/utils.ts 文件，导出一个工具函数
  2. 在 app/page.tsx 中用 @/lib/utils 路径导入并使用
  3. 验证路径别名正确工作

练习 3：切换 Bundler（高阶）

  1. 分别用 pnpm dev 和 pnpm dev -- --webpack 启动
  2. 修改文件，对比两种 bundler 的 Fast Refresh 速度
  3. 记录观察结果

练习 4：团队选型评估（资深）

列出一个评估表格，比较 ESLint vs Biome、pnpm vs npm vs yarn vs bun 的优缺点，并给出你的推荐理由。

十三、源码对照

对应源码位置（高阶/架构层级参考）

功能源码文件行数
CLI 入口packages/next/src/bin/next.ts704
create-next-apppackages/create-next-app/整个包
Dev 命令packages/next/src/cli/next-dev.ts~600
Fast Refreshpackages/next/src/client/next-dev.ts-

你可以用以下命令查看 CLI 入口代码的结构：

# 查看 CLI 支持的命令
grep -n "command\|Command" packages/next/src/bin/next.ts | head -20

十四、关键要点总结

  1. Next.js 是 React 全栈框架，不仅仅是 SSR 方案
  2. pnpm create next-app@latest --yes 是最快的开始方式
  3. Turbopack 是默认 bundler，用 --webpack 切换
  4. next dev / next build / next start 是三个核心脚本
  5. App Router（app/ 目录）是推荐的路由系统
  6. 路径别名 @/ 让导入更简洁
  7. Fast Refresh 让开发体验极佳
  8. Next.js 16 起 next build 不再自动运行 linter

下一课：第 2 课：文件系统路由 — 用文件夹定义你的应用结构

avatar
文章
阅读
粉丝