Next.js 入门

如果你已经会写一点 React，第一次打开 Next.js 文档时，反而可能更迷糊：React 组件还是那些组件，项目里却突然多了 app、layout.tsx、Server Components、构建与部署等一整套概念。它们不是为了把简单事情复杂化，而是在回答一个 React 组件本身没有回答的问题：怎样把组件组织成一个可以访问、取数、渲染和上线的完整 Web 应用？

这一章不要求你一开始就记住所有术语。我们先建立一幅能用的地图，再亲手创建一个项目。读完后，你应该能独立完成这些动作：检查环境、运行 create-next-app、读懂核心目录、改出首页、添加第二个页面、放入一个小型客户端交互，并分清开发服务器与生产构建。

React 组件经过 Next.js 的路由、渲染、数据与部署能力组成完整 Web 应用的手绘示意图

Next.js 没有取代 React，它把路由、渲染、数据与部署这些应用级问题放进同一套约定。

这门课以 App Router 为主。Next.js 仍然支持较早的 Pages Router，所以你搜索问题时可能看到 pages/、getServerSideProps 或 _app.tsx。这些内容不一定错误，但不能直接和 App Router 教程混用。先看清教程针对哪一种路由器，能省掉很多无谓排查。

Next.js 到底补上了什么

React 解决的是用户界面问题。我们用组件描述页面，用 props 传数据，用 state 表达会变化的界面。可是一个真实网站还需要知道：访问 /about 时应显示哪个组件，数据应在服务器还是浏览器读取，首屏 HTML 从哪里来，图片和字体怎样加载，以及最终产物怎样运行。

Next.js 是建立在 React 之上的全栈 Web 框架。这里的“全栈”不意味着每个项目都必须自建数据库，也不意味着前后端从此不能拆开。它表示同一套框架既能组织浏览器里的界面，也能承载服务器侧的数据读取、请求处理与渲染。你的后端完全可以仍是 Java、Go 或独立 API；Next.js 负责把 Web 应用这一侧的工作连接起来。

可以先把框架提供的能力归成六类：

路由约定：目录和特殊文件共同决定 URL 与页面层级。
渲染模型：页面可以在服务器生成，也可以在需要时给局部交互发送客户端 JavaScript。
数据能力：Server Components 可以靠近数据源取数；Route Handlers 可以处理 HTTP 请求。
资源优化：框架提供图片、字体、CSS、元数据等常用能力。
开发工具链：编译、打包、Fast Refresh、TypeScript 与错误提示已经接入项目。
交付方式：应用可以运行成 Node.js 服务、Docker 容器或受限功能的静态导出，也可以交给支持 Next.js 的平台部署。

不要把 Next.js 只理解成“React 加 SSR”

服务端渲染只是其中一部分。App Router 还会根据数据、缓存与路由需要决定何时预渲染、何时按请求渲染，并通过流式传输逐步交付内容。初学阶段不需要马上掌握这些策略，但要保留一个准确判断：Next.js 管理的是一条完整的页面生产链，不只是把 React 组件搬到服务器执行一次。

我们接下来观察项目时，可以反复问三个问题：

这个 URL 由哪个文件负责？
这段代码在哪个环境运行？
浏览器实际收到了 HTML、RSC 数据还是客户端 JavaScript？

只要这三个问题逐渐清楚，后面的路由、数据获取和缓存就不会变成彼此孤立的 API。

动手前先把环境对齐

当前官方安装要求的最低 Node.js 版本是 20.9，支持 macOS、Windows（包括 WSL）和 Linux。实际学习时，我更建议安装 Node.js 官网标记的当前 LTS 版本：它通常比最低版本更适合长期使用，也更容易和新工具保持兼容。

Next.js 开发前检查操作系统、Node.js 20.9 以上、包管理器、编辑器、浏览器与前置知识的手绘清单

框架问题常常先从环境问题查起；确认 Node.js 版本与包管理器，再开始排查代码。

打开终端，先运行：

shell

node --version
npm --version
npx --version

第一条会显示 Node.js 版本。如果主版本和次版本低于 20.9，先升级 Node.js，再创建项目。后两条用来确认 npm 与 npx 可用。npm 负责安装依赖与运行脚本，npx 可以临时执行 create-next-app，无需先把脚手架全局安装到电脑上。

“终端能找到 node”不等于版本一定正确。一台电脑上可能同时存在系统 Node、版本管理器安装的 Node 和编辑器终端使用的 Node。遇到版本报错时，以当前终端实际输出的 node --version 为准。

需要先学到什么程度

Next.js 官方入门材料默认读者了解 HTML、CSS、JavaScript 与 React。你不必先成为 React 专家，但至少应认识组件、props、JSX、模块导入与基本 state。如果下面的函数组件完全陌生，先复习 React 基础会更顺：

tsx

type GreetingProps = {
  name: string
}
 
export default function Greeting({ name }: GreetingProps) {
  return <p>你好，{name}！</p>
}

包管理器只选一个

Next.js 支持 npm、pnpm、Yarn 和 Bun。课程示例统一使用 npm，不代表其他工具不能用。真正重要的是在同一个项目里保持一致：看见 package-lock.json 就继续用 npm，不要又生成 pnpm-lock.yaml 或 yarn.lock。多个锁文件会让团队成员和部署平台难以判断应采用哪一组依赖解析结果。

按照当前官方要求，创建新 Next.js 项目时 Node.js 至少需要哪个版本？

用 create-next-app 创建项目

在你准备存放代码的目录中运行：

shell

npx create-next-app@latest nextjs-notes --use-npm

这条命令可以拆开读：

npx 临时执行一个 npm 包中的命令。
create-next-app@latest 使用当前最新的项目脚手架。
nextjs-notes 是项目名，也是即将创建的目录名。
--use-npm 明确让脚手架用 npm 安装依赖并生成 package-lock.json。

脚手架会先问你是否使用推荐默认配置。当前推荐组合包括 TypeScript、ESLint、Tailwind CSS、App Router 与 Turbopack，默认导入别名是 @/*。Turbopack 已是开发与构建命令的默认打包器，所以不要再照着旧教程寻找“是否启用 Turbopack”的提问。

create-next-app 从创建命令经过 TypeScript、ESLint、Tailwind、App Router 和 Turbopack 默认配置到启动开发服务器的手绘流程图

第一次创建可以看一遍交互式提问；需要团队复现时，再用明确参数或记录好的选择固定项目骨架。

初学者怎样选

如果这是你的第一个项目，直接选择推荐默认配置就够了。想逐项理解时，可以选择自定义：

TypeScript：建议开启。类型错误通常比运行后的界面错误更早暴露。
Linter：ESLint 与 Biome 都是有效选择。本课程示例按推荐默认的 ESLint 说明。
React Compiler：它不是理解 Next.js 的前置条件。初学时可以保持默认，不必为追求“配置更多”而开启。
Tailwind CSS：推荐默认会开启；它是样式方案，不是路由或渲染的必要条件。
src/ 目录：只影响源码放在根目录还是 src/ 下。本课程为了路径简洁，使用根目录的 app/。
App Router：选择它。本课程后续内容都以这一套路由模型展开。
导入别名：保留默认 @/*，稍后可以用 @/app/... 或 @/components/... 代替很长的相对路径。

需要一条更明确、便于复制到团队文档的命令时，可以写成：

shell

npx create-next-app@latest nextjs-notes --ts --eslint --tailwind --app --use-npm

--yes 也能跳过提问，但它可能使用默认值或之前保存的偏好。想得到可复现的项目骨架，显式参数通常更容易审查。

下面的配置规划器会根据你的选择实时生成命令。先试试推荐组合，再关闭 Tailwind 或切换 src/，观察哪些只是组织选择，哪些会改变本课程使用的路由模型。

先确认当前终端中的 Node.js 不低于 20.9，并决定本项目统一使用哪一个包管理器。

在准备存放项目的父目录执行 create-next-app。不要先手动创建同名且已有文件的目录，否则脚手架可能因目录不为空而停止。

第一次学习采用推荐默认配置，或用明确参数固定 TypeScript、ESLint、Tailwind 与 App Router。

等待依赖安装完成，确认终端没有错误，再进入新生成的项目目录。网络慢和安装失败是两回事，先看最后几行输出再判断。

当前 create-next-app 的推荐默认组合包含哪些项目？

先看懂项目骨架

进入项目目录：

shell

cd nextjs-notes

不同脚手架版本与选择会让文件略有差异。使用上面的推荐组合时，你通常会看到类似结构：

text

nextjs-notes/
├── app/
│   ├── favicon.ico
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
├── public/
├── eslint.config.mjs
├── next.config.ts
├── package.json
├── package-lock.json
├── postcss.config.mjs
└── tsconfig.json

我们先只抓住真正会立刻用到的部分。

app 是路由与界面的核心目录

app/page.tsx 对应根路径 /。page.tsx 必须默认导出一个 React 组件，Next.js 才能把这个路由公开成页面。

app/layout.tsx 是根布局。它包裹所有页面，并且必须包含 <html> 与 <body>。适合放全站共享的语言标记、导航、字体、全局样式入口和元数据。

app/globals.css 保存全局样式。推荐模板通常在根布局中导入它。全局样式应该处理真正全局的规则；具体组件的样式仍可用 Tailwind 或 CSS Modules 组织。

public 保存直接访问的静态文件

放在 public 下的文件从网站根路径访问。例如：

text

public/logo.png  →  /logo.png
public/docs/start.pdf  →  /docs/start.pdf

URL 中不写 public。如果用 next/image 显示本地图片，也会从类似 /logo.png 的路径引用。

配置文件各管一件事

package.json 记录依赖与可运行脚本，是排查“这个项目到底支持什么命令”的第一站。
tsconfig.json 控制 TypeScript，也保存 @/* 等路径别名。
eslint.config.mjs 保存 ESLint 规则。
postcss.config.mjs 连接 Tailwind 等 CSS 处理工具。
next.config.ts 放 Next.js 项目级配置。刚入门时通常无需修改。
package-lock.json 固定 npm 解析出的依赖版本，应随项目保存。

运行开发或构建命令后还会出现 .next/。它是生成目录，不是手写源码，也不应该拿来修改页面。

app 目录允许放普通组件、工具函数和样式文件。普通文件不会仅仅因为位于 app 中就自动成为页面；路由是否公开由 page、route 等特殊文件决定。后续课程会专门展开完整的特殊文件规则。

运行并改出第一个页面

确认终端当前就在含有 package.json 的项目根目录，然后启动开发服务器：

shell

npm run dev

终端会显示实际访问地址，通常是 http://localhost:3000。如果 3000 端口被占用，以终端给出的结果为准。开发服务器会保持运行；需要继续输入其他命令时，可以另开一个终端标签页。

打开 app/page.tsx，把模板内容改成一个足够简单的首页：

tsx

export default function HomePage() {
  return (
    <main className="mx-auto min-h-screen max-w-3xl px-6 py-16">
      <p className="text-sm font-semibold text-blue-600">第一站</p>
      <h1 className="mt-3 text-4xl font-bold">我的 Next.js 学习站</h1>
      <p className="mt-5 text-lg text-slate-600">
        如果你能看到这句话，首页已经由 app/page.tsx 成功渲染。
      </p>
    </

保存文件后，浏览器会通过 Fast Refresh 更新。Fast Refresh 的目标不是简单粗暴地整页刷新，而是在开发阶段尽量快速反映模块变化并保留可保留的状态。如果页面没有变化，先看终端和浏览器错误，不要连续重启服务器掩盖真正问题。

根布局决定共享外壳

推荐模板已经生成 app/layout.tsx。可以把语言和基础元数据改成自己的内容：

tsx

import type { Metadata } from 'next'
import './globals.css'
 
export const metadata: Metadata = {
  title: '我的 Next.js 学习站',
  description: '记录 Next.js 学习过程与练习',
}
 
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode
}>) {
  return

这里的 children 就是当前匹配页面的内容。访问首页时，它会被 app/page.tsx 的结果替换；以后访问关于页时，它会换成关于页，但根布局仍然包在外面。

在 App Router 中，只要在 app 目录创建一个普通文件夹，该文件夹就会立刻变成可访问页面。

用最小模型理解 App Router

App Router 最直观的规则是：文件夹对应 URL 片段，page.tsx 提供这个 URL 的页面，layout.tsx 提供共享外壳。

App Router 文件树与根路径、关于页、动态博客页和 public 静态资源 URL 的手绘对应图

文件夹定义路由片段，page.tsx 暴露页面，layout.tsx 提供共享外壳；普通文件夹本身不会自动成为可访问页面。

在 app 中创建 about/page.tsx：

tsx

export default function AboutPage() {
  return (
    <main className="mx-auto max-w-3xl px-6 py-16">
      <h1 className="text-4xl font-bold">关于这个学习站</h1>
      <p className="mt-5 text-slate-600">
        这里记录我对路由、渲染与数据获取的理解。
      </p>
    </main>
  )
}

目录与 URL 的对应关系是：

text

app/about/page.tsx  →  /about

然后在首页导入 Link，增加内部导航：

tsx

import Link from 'next/link'
 
export default function HomePage() {
  return (
    <main className="mx-auto min-h-screen max-w-3xl px-6 py-16">
      <p className="text-sm font-semibold text-blue-600">第一站</p>
      <h1 className="mt-3 text-4xl font-bold">我的 Next.js 学习站</h1>
      <p className="mt-5 text-lg text-slate-600">
        如果你能看到这句话，首页已经成功渲染。

next/link 提供客户端过渡与预取等路由优化，是站内页面导航的主要方式。普通 <a> 仍适合外部网址、下载等场景，但站内页面不要习惯性地用它触发完整页面加载。

下面的互动页把路由匹配、根布局、服务器渲染、HTML 与局部水合放到一条时间线上。切换“纯服务器页面”和“带客户端计数器”，观察最后一站是否需要执行。

要让 /about 成为可访问页面，对应的文件路径是 ____。

Server Components 与客户端交互

App Router 中的页面和布局默认是 Server Components。这意味着组件可以在服务器环境运行、靠近数据源读取数据，并减少发送到浏览器的 JavaScript。它们不需要写一个特殊的“服务器”标记。

需要 state、事件处理器、useEffect、自定义 Hooks 或 window、localStorage 等浏览器 API 时，才创建 Client Component，并在文件最上方写 'use client'。

Server Components 在服务器生成 HTML 与 RSC 数据，浏览器先显示页面，再由 Client Components 水合接上交互的手绘流程图

App Router 默认把页面与布局留在服务器；需要状态、事件或浏览器 API 的小块再进入客户端边界。

在 app/ui/counter.tsx 创建一个最小交互组件：

tsx

'use client'
 
import { useState } from 'react'
 
export default function Counter() {
  const [count, setCount] = useState(0)
 
  return (
    <section className="mt-8 rounded-xl border border-slate-200 p-5">
      <p>当前练习次数：{count}</p>
      <button
        className="mt-3 rounded-lg bg-slate-900 px-4 py-2 text-white"

再把它导入默认的 Server Component 页面：

tsx

import Counter from './ui/counter'
 
export default function HomePage() {
  return (
    <main className="mx-auto min-h-screen max-w-3xl px-6 py-16">
      <h1 className="text-4xl font-bold">我的 Next.js 学习站</h1>
      <Counter />
    </main>
  )
}

这里没有必要给 app/page.tsx 也加 'use client'。页面可以继续留在服务器，只让计数器及它导入的客户端子树进入客户端模块图。边界越贴近真正交互的小组件，发送给浏览器的 JavaScript 通常越少。

use client 不等于“只在浏览器出现”

首次访问时，Next.js 仍会为 Client Components 预渲染 HTML，让用户先看到非交互预览；浏览器加载相关 JavaScript 后再进行水合，把事件处理器接到现有 DOM 上。'use client' 定义的是模块边界和能力边界，不是关闭首屏预渲染的开关。

两条安全边界要记住

Server Component 可以读取数据库或服务器环境中的秘密，但不能把秘密当成 props 传给 Client Component。传入客户端的 props 需要能被 React 序列化，而且它们最终对浏览器可见。

Client Component 也不是使用浏览器 API 的“随意通行证”。初始预渲染与浏览器首次渲染必须一致。如果在渲染阶段直接依赖 Date.now()、随机数或 window 分支，容易造成水合不匹配。浏览器专属副作用通常放进事件处理器或 useEffect，并设计稳定的首次输出。

不要为了消除一个 Hooks 报错，就把根布局或整个页面都标成客户端组件。先找到真正需要 state、事件或浏览器 API 的最小模块，在那个文件顶部建立客户端边界。

页面中只有一个点赞按钮需要 useState，哪种做法更合适？

开发模式和生产模式不是一回事

项目里的 package.json 通常会包含这些脚本：

json

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

实际脚本以你的 package.json 为准，不要因为某篇教程出现了命令，就假设当前项目一定定义了同名脚本。

npm run dev 启动开发服务器，当前默认使用 Turbopack，重点是快速反馈、错误覆盖层与 Fast Refresh。
npm run build 生成并验证优化后的生产构建。开发页面能打开，不代表生产构建一定通过。
npm start 运行已经成功生成的生产构建；它不会替你先做构建。
linter 要按项目脚本单独运行。Next.js 16 起，next build 不再自动运行 linter。

Next.js 使用开发服务器、编辑页面、Fast Refresh、错误检查、独立代码检查和生产构建组成的手绘开发闭环

开发阶段追求快速反馈，交付前则要分别确认代码检查和生产构建；两条通过才算真正可交付。

准备交付时，可以按这个顺序理解，而不是机械背命令：

在开发服务器中完成页面修改，并清理终端与浏览器里真正的运行错误。

查看 package.json，按项目实际配置单独运行 ESLint、Biome 或其他代码检查工具。

运行生产构建。构建会暴露类型、导入、服务端与客户端边界等开发浏览时未必触发的问题。

构建成功后，才用 start 脚本本地运行生产服务，或交给目标平台的部署流程。

下面的检查站把开发反馈轨和生产交付轨拆开。故意选择“构建前直接 start”或“dev 正常就部署”，看看缺少哪张通行票。

部署不只等于 Vercel

Vercel 对 Next.js 提供低配置部署和框架集成，但 Next.js 也可以部署为 Node.js 服务或 Docker 容器，这两种方式支持完整框架能力。静态导出可以放到只提供静态文件的主机，但服务器相关能力会受限。选择部署方式时，应先看应用用了哪些能力，再看目标平台是否支持，而不是把框架与某一家托管服务画等号。

只要 npm run dev 能正常打开首页，就可以确定生产构建和代码检查一定通过。

新手最常遇到的误区

很多入门问题不是 API 太难，而是心智模型混在一起。下面这张排查表比“删掉重装”更值得先看。

现象	常见原因	先做什么
脚手架提示 Node.js 版本不支持	当前终端使用了旧 Node	运行 `node --version`，确认至少为 20.9，并检查终端使用的实际安装位置
`npm run dev` 找不到脚本或找不到 Next.js	终端不在项目根目录，或依赖安装没有完成	找到含 `package.json` 的目录，查看其中的 scripts 与安装输出
访问 `/about` 得到 404	只有 `app/about/` 文件夹，没有 `page.tsx`，或项目实际使用了 `src/app`	对照项目真实目录确认 `app/about/page.tsx` 的位置
在页面使用 `useState` 时出现边界错误	页面默认是 Server Component	把交互部分提取成小型 Client Component，并在它的文件顶部写 `'use client'`
浏览器提示 hydration mismatch	首次服务器输出与浏览器首次渲染不同	排查时间、随机数、浏览器 API、无效 HTML 嵌套，保持首次输出稳定
旧教程里的 API 无法使用	把 Pages Router 写法放进了 App Router	先确认教程目录是 `pages` 还是 `app`，再找对应版本的文档
dev 正常但 build 失败	某些类型、导入或生产约束尚未在当前访问路径触发	读构建错误的第一处有效堆栈，不要用反复重启开发服务器代替修复
样式突然失效	全局 CSS 没有在根布局导入，或项目根本没启用 Tailwind	检查 `app/layout.tsx`、`app/globals.css` 与实际脚手架选择

一个很容易被忽略的路径差异

如果创建项目时选择了 src/，教程中的 app/page.tsx 在你的项目里会是 src/app/page.tsx。@/* 别名通常也会对准源码根。不要看到路径不同就复制出第二个 app 目录；先读 tsconfig.json 与现有目录结构。

不要用“全部客户端化”绕开报错

给越来越上层的文件加 'use client'，短期可能让 Hooks 报错消失，却会扩大客户端 JavaScript 边界，还可能让服务器专属代码无法使用。正确的排查方式是先标出交互点，再把边界放到最小的可交互子树。

做一个可复现的入门练习

现在先离开模板首页，做一个“学习记录站”。要求如下：

首页标题改成“我的 Next.js 学习记录”。
新增 /notes 页面，写下三条准备学习的主题。
首页用 Link 跳转到 /notes。
新建一个 Client Component 按钮，记录今天完成了几项练习。
保持首页与根布局为 Server Components，不给它们添加 'use client'。
用开发服务器确认交互，再按 package.json 检查代码并完成一次生产构建。

先自己动手。如果页面路径或客户端边界拿不准，再展开参考结构。

参考目录可以是：

text

app/
├── notes/
│   └── page.tsx
├── ui/
│   └── practice-counter.tsx
├── layout.tsx
└── page.tsx

app/notes/page.tsx 仍是默认的 Server Component：

tsx

export default function NotesPage() {
  const topics = ['文件系统路由', 'Server Components', '数据获取']
 
  return (
    <main className="mx-auto max-w-3xl px-6 py-16">
      <h1 className="text-4xl font-bold">学习主题</h1>

练习项目的 app/notes 文件夹中只有一个 topics.ts 数据文件，没有 page.tsx。访问 /notes 会怎样？

离开这一页前做一次自检

你不需要背下所有文件约定，但应该能不看答案说清楚下面几件事：

React 负责组件与界面，Next.js 还补上路由、渲染、数据、优化、工具链与交付约定。
当前新项目要求 Node.js 至少为 20.9，项目内只使用一种包管理器。
推荐脚手架默认采用 TypeScript、ESLint、Tailwind、App Router 与 Turbopack。
app/page.tsx 对应 /，app/about/page.tsx 对应 /about，根布局包裹它们。
页面与布局默认是 Server Components；state、事件和浏览器 API 才需要客户端边界。
dev、代码检查、build 和 start 各自回答不同问题，不能互相替代。

如果其中某一条仍然模糊，回到对应交互页再走一遍流程。下一步再展开项目结构与完整路由约定，会比一开始死记所有特殊文件更稳。

tsx

'use client'
 
import { useState } from 'react'
 
export default function PracticeCounter() {
  const [completed, setCompleted] = useState(0)
 
  return (
    <div>
      <p>今天已完成 {completed} 项练习</p>
      <button type="button" onClick={() => setCompleted((value) => value + 1)}>
        记录一项
      </button>
    </div>
  )
}

Next.js 入门 | 自在学