Next.js 从第一行代码到上线

0030 秒速览：先拿走这三句话

如果只记三句话

1. 文件夹就是网址：在 app/about/ 里放一个 page.tsx，你就自动多了一个 /about 页面，不用填任何路由表。
2. 默认在服务器上跑，要交互才切成浏览器：组件默认在服务端拼好 HTML 再发出去，只有点击、输入、动画这些必须在浏览器里发生的事，才在文件顶部加一行 "use client"。
3. 先 build 再上线：npm run dev 能跑不等于能上线，npm run build 过了才是真的过了。

一张表：你现在的处境 → 该看哪几节

关键数字先给量级

上手路径：五步，今晚能走完

新手最容易提前踩的三个坑

01Next.js 到底是什么（先破四个错想）

它不是一门新语言，也不是 React 的替代品

这是最容易搞错的第一处。React 是一个画界面的库：你告诉它「这块内容长什么样」，它负责把画面渲染出来。它只管画面，不管你网站的地址怎么分、数据从哪来、接口写在哪、上线之后跑在哪。

Next.js 是建在 React 之上的一整套约定加工具。所谓「约定」，意思是它不给你一堆开关去配，而是规定「你把文件放在这个名字下、用这个名字命名，我就知道你想干什么」。你少配很多东西，代价是要先记住这套命名规则。

四个最常见的错想，逐个破掉

它和你已经见过的「网站」差在哪

用你每天都在经历的体验来说明。传统的纯前端 React 项目，你打开网址时会先看到一片空白，然后页面的字才一个一个冒出来——因为浏览器得先下载一大包 JavaScript，再自己把页面拼出来。如果你的网慢，这个空白会持续一两秒。

Next.js 默认换了个做法：它先在服务器上把页面拼成完整的 HTML 文字，再把这份拼好的结果发给你。浏览器拿到就能直接画出来，所以你看到的是内容，不是空白。拼好之后，它再悄悄把 JavaScript 送下来，让按钮、输入框这些能点能动——这一步的行业叫法是「注水」（hydration），意思是给已经画好的静态骨架注入生命力。

它内部有哪几块拼图

版本这件事，你要知道的方法

本文写定时的最新稳定版是 16.3.5（2026-09-11 发布）。Next.js 大约每几个月出一个大版本，而你手里的 AI 助手、教程、搜索结果里混着好几个版本的写法——这是新手最容易被带偏的地方。

所以给你一条比「记住版本号」更有用的做法：在项目里问版本，而不是在脑子里记版本。

# 看你的项目装的是哪个版本
npm ls next

# 看当前最新稳定版是几
npm view next version

02它替你做了什么：六个问题一次答完

用纯 React 做网站，你会接连撞上六个问题。Next.js 的价值就是这六个问题它都有现成答案。

问题一：地址栏里的 /about，怎么对应到一个页面？

纯 React 项目里，地址和页面的对应关系得你自己搭（要装一个专门的库，写一份路由表，再手动维护它和文件的同步）。Next.js 的做法是：你把文件放对位置，网址就自动有了。

app/about/page.tsx   →   网址 /about
app/blog/page.tsx    →   网址 /blog
app/page.tsx         →   网址 /（首页）

这就是「文件即路由」。行业的通俗说法也叫「约定优于配置」——用一套命名规矩，换掉一大堆要你手填的配置文件。

顺便先埋一个你会反复遇到的词：middleware（直译「中间件」）。它指的是「请求进入页面之前先替你看一眼的那道关卡」，用来做登录拦截、跳转这类事。本文第 10 节会专门讲它——因为 16 版刚把它改了名字，那是本文要提醒你的第二个「旧教程会把你带偏」的地方。

问题二：搜索引擎抓不到我的内容怎么办？

搜索引擎派来的自动程序（行业叫爬虫）读的是服务器返回的原始 HTML。纯前端渲染的页面，返回的原始 HTML 几乎是空的，内容是浏览器后来用 JavaScript 拼上去的——爬虫未必等得及。Next.js 默认就在服务器把内容放进 HTML 里，爬虫一读就读到。

问题三：接口写在哪？

你不需要另起一个后端项目。在 app/api/hello/route.ts 里导出一个函数，/api/hello 就是一个能返回 JSON 数据的接口（JSON 是一种人和机器都好读的文本数据格式）。

问题四：图片太大、加载慢？

用官方的 Image 组件替代原生的 <img> 标签，它自动压缩、按需加载、并预留位置防止页面跳动。

问题五：上线要折腾多久？

把代码推到 GitHub，在 Vercel 上导入这个仓库，点一次部署。之后每次推送代码，网站自动更新。

问题六：AI 助手总给我写旧版 API 怎么办？

16 版的脚手架会随项目生成一份 AGENTS.md（给 AI 助手看的说明书），里面写明「请以本版本官方文档为准」。你也可以手动把它补到旧项目里：

npx @next/codemod@canary agents-md

六个问题，一张表收口

03什么场景该用它，什么场景别用

一句话判断法

问自己：我要做的是「一个能在网上打开的完整网站」，还是「一段练习代码」？前者用 Next.js，后者别用。它给你的每一样好处（路由、渲染、部署）都只在「要发布出去」时才兑现；你只在自己电脑上练语法时，这些全是白背的负担。

该用它的五种场景

别用它的三种场景

和别的方案比：新手选型表

下面三条不是「谁更好」，是「谁的代价你更愿意付」。

「适合谁 / 不适合谁」——放在这里而不是开头

04从零装到跑起来

这一节的目标很具体：十五分钟内，你的浏览器里出现一个属于你的页面，改一个字它自动变。全程只有四条命令。

第一步：确认你的 Node 版本够不够

Node.js 是让 JavaScript 能脱离浏览器、在你电脑上直接运行的程序（行业叫「运行时」）。Next.js 依赖它。打开终端（Mac 上按 Command + 空格，输入「终端」回车），敲：

node -v
# 要看到 v20.9.0 或更高。推荐 v20 或 v22 的 LTS（长期支持）版
npm -v
# 能输出版本号就说明 npm（Node 自带的包管理器）可用

还没装 Node？三步装好

第二步：一条命令建项目

npx create-next-app@latest my-app
# my-app 是文件夹名，换成你想要的名字，比如 my-blog
# npx 的意思是「临时下载这个工具跑一次，不用先装到全局」

它会问你几个问题。16 版的流程被简化过：第一个问题选「用推荐配置」，剩下的问题就只剩「项目叫什么名字」。

第三步：启动，并确认真的成功了

cd my-app
npm run dev
# 终端出现 "Ready in Xms" 并且给出 http://localhost:3000

浏览器打开 http://localhost:3000，看到 Next.js 的欢迎页就对了。然后改一个字试试：打开 app/page.tsx，随便改一句文案，保存，回到浏览器——页面自己变了。这个能力叫热更新：不用手动重启服务器，改完就生效。

装出来的项目里都有什么

my-app/
├── app/                  # 页面和路由都住这里（你 90% 的时间在这）
│   ├── layout.tsx        # 全站外壳：导航栏、页脚写这里
│   ├── page.tsx          # 首页，对应网址 /
│   └── globals.css       # 全局样式
├── public/               # 图片、图标等静态文件，引用时从 / 开头
├── next.config.ts        # Next.js 的配置文件
├── tsconfig.json         # TypeScript 配置（自动生成，先别动）
├── package.json          # 依赖清单和三条脚本：dev / build / start
└── AGENTS.md             # 给 AI 助手的版本说明书（16 版自带）

三个常用命令，先分清它们的场合

装的过程中卡住了

05最小例子：两个页面 + 一个能点的链接

目标：亲手验证「文件即路由」。做完你会有首页、关于页，以及它们之间不刷新的跳转。全程不用改任何配置。

第 1 步：确认项目正在跑

终端里 npm run dev 保持开着，浏览器能打开 localhost:3000。

第 2 步：把首页换成你自己的话

打开 app/page.tsx，把 return ( ... ) 里的内容换掉，保存，看浏览器自己变。这一步是在验证热更新通不通。

第 3 步：新建一个关于页

新建文件夹 app/about/，在里面新建文件 page.tsx。访问 http://localhost:3000/about——页面出现了，而你一行路由配置都没写。

第 4 步：让两个页面能互相跳

// app/page.tsx —— 首页
import Link from "next/link";

export default function Home() {
  return (
    <main>
      <h1>我的第一个 Next.js 网站</h1>
      <p>改一行字、保存、浏览器自动变——这就是热更新。</p>
      <Link href="/about">去关于页看看 →</Link>
    </main>
  );
}

// app/about/page.tsx —— 关于页
import Link from "next/link";

export default function About() {
  return (
    <main>
      <h1>关于我</h1>
      <p>这个文件住在 app/about/page.tsx，所以网址是 /about。</p>
      <p>这就是「文件即路由」：文件夹名 = 网址路径。</p>
      <Link href="/">← 回首页</Link>
    </main>
  );
}

为什么用 Link 而不是 <a> 标签

Link 是 Next.js 提供的链接组件，它做的是客户端跳转：只换掉页面内容，不整页重新加载。你看到的效果是切换很快、页面不闪白，而且页面上已填了一半的表单不会被清空。

用它自己的原话说，它通过「预取」（prefetch）提前把目标页准备好——你把鼠标移到链接上时，浏览器已经在悄悄下载下一页了。

做完请确认这三条

顺手加一点样式（可选）

脚手架带了 Tailwind：不写 CSS 文件，直接在 className 里写类名。把首页的 <main> 换成下面这样，立刻像个正经网站：

// app/page.tsx —— 只换样式，逻辑一个字没动
<main className="max-w-2xl mx-auto p-8">
  <h1 className="text-3xl font-bold mb-4">我的第一个 Next.js 网站</h1>
  <p className="text-gray-400 mb-6">改一行字、保存、浏览器自动变——这就是热更新。</p>
  <Link href="/about" className="text-indigo-400 underline">
    去关于页看看 →
  </Link>
</main>

06四个文件名，决定一个页面能不能被访问

这一节是全文最该记住的一节。Next.js 的「魔法」全靠这四个名字，写错一个字母，页面就是 404。

四个特殊文件名分别是干什么的

为什么 page.tsx 这个名字不能省

因为 Next.js 用「有没有 page.tsx」来判断「这个文件夹算不算一个可访问的网址」。你可以有 app/blog/ 文件夹，里面放着组件、工具函数、样式；只要没有 page.tsx，/blog 就打不开。这不是限制，是给「只想放文件、不想开页面」留的空间。

layout.tsx：导航栏只写一次，全站生效

根 layout.tsx 是每个页面外面那层壳。你把导航栏写在这里，所有页面自动都有——不用每个页面复制一遍。

// app/layout.tsx —— 根外壳，所有页面都会被它包住
import Link from "next/link";
import "./globals.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh-CN">
      <body>
        <nav>
          <Link href="/">首页</Link> |{/* 导航只写这一次，全站生效 */}
          <Link href="/about">关于</Link> |
          <Link href="/blog">博客</Link>
        </nav>
        <hr />
        {children}{/* 每个页面的内容会被塞到这里 */}
        <footer>© 2026 我的小站</footer>
      </body>
    </html>
  );
}

layout.tsx 可以嵌套：不同板块穿不同外壳

把 layout.tsx 放进子文件夹，它就只包住那个文件夹里的页面。营销页一套外壳、后台另一套外壳，互不干扰——第 08 节的路由组就是为这个场景准备的。

节点级兜底：loading.tsx 与 error.tsx

// app/blog/loading.tsx —— 进博客分区先看到它，数据到了自动替换
export default function Loading() {
  return <p>正在加载文章列表…请稍候</p>;
}

// app/blog/error.tsx —— 这个分区出错时的兜底界面
"use client"; // error.tsx 必须是客户端组件：它要能响应点击
export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <main>
      <h1>出了一点小问题</h1>
      <p>{error.message}</p>
      <button onClick={reset}>再试一次</button>
    </main>
  );
}

07服务端组件和客户端组件：一条分界线，两套后果

这是 App Router 最核心、也最容易把人卡住的新概念。本节按五步拆：它不是什么 → 它是什么 → 怎么运作 → 为什么重要 → 新手坑在哪。

第一步：它不是「前端项目 vs 后端项目」那种分工

你可能会想：「服务端」和「客户端」听起来像是要建两个项目、或者两个文件夹，一个写后端一个写前端。

不是。这两个词说的不是项目、不是文件夹、也不是两种文件类型。它指的是同一份组件代码，在哪个地方被执行——是在你租的那台服务器上执行完再发结果，还是在访客的浏览器里执行。

第二步：它到底是什么——一行声明决定运行位置

在 app/ 里写的每一个组件，默认都是服务端组件：它在服务器上执行、把结果拼成 HTML 发出去，自身不往浏览器发送 JavaScript。行业缩写叫 RSC（React Server Component 的首字母）。

如果你想让某个组件变成客户端组件（在浏览器里跑、能响应点击和输入），就在那个文件的最顶部写一行：

"use client"; // 这一行写在文件最顶端，声明「我在浏览器里跑」

import { useState } from "react";

export default function Counter() {
  const [n, setN] = useState(0);
  return <button onClick={() => setN(n + 1)}>点了 {n} 次</button>;
}

第三步：怎么运作——一句话版本

服务端组件在服务器执行，可以直接读数据库、用密钥调外部接口，这些代码和密钥都不会下发到浏览器；渲染出来的结果（HTML）发给浏览器。

客户端组件会被打包进 JavaScript 一并下发，浏览器拿到后接手，恢复点击、输入、动画这些交互能力——这一步行业叫「注水」（hydration），意思是给已经画好的静态页面注入生命力。

第四步：为什么这个默认值重要

第五步：新手坑在哪（对照看，一眼就懂）

// 没加 "use client"，却用了 useState → 运行时报错
import { useState } from "react";

export default function Counter() {
  const [n, setN] = useState(0);
  return <button onClick={() => setN(n + 1)}>{n}</button>;
}

"use client"; // 顶行声明：我在浏览器里跑
import { useState } from "react";

export default function Counter() {
  const [n, setN] = useState(0);
  return <button onClick={() => setN(n + 1)}>{n}</button>;
}

该把 "use client" 加在哪一层

这是最容易加错的地方。惯例是加到最末端的叶子组件上，不要加到整页。

// ✅ 推荐：页面本身是服务端组件，只有按钮那一小块是客户端
// app/blog/page.tsx
import LikeButton from "./like-button";

export default async function Blog() {
  const posts = await getPosts(); // 服务端取数据
  return (
    <ul>
      {posts.map((p) => (
        <li key={p.id}>
          {p.title}
          <LikeButton id={p.id} />{/* 只有它标了 "use client" */}
        </li>
      ))}
    </ul>
  );
}

反过来的做法——在 app/blog/page.tsx 顶部直接写 "use client"——会让整页都变成客户端渲染，你前面赚到的首屏快、体积小全部还回去。这是新手最常见的一种「明明照抄了却更慢」。

四条边界，记成一张表

08路由：文件夹名就是网址

三类文件夹能覆盖 90% 的路由需求：普通嵌套、动态参数、分组。只要记住括号和方括号的区别。

嵌套：文件夹套文件夹

app/
├── page.tsx                      # → /
├── about/
│   └── page.tsx                  # → /about
└── blog/
    ├── page.tsx                  # → /blog（列表页）
    └── first-post/
        └── page.tsx              # → /blog/first-post（详情页）

动态参数：一个文件接住无数个网址

博客有几百篇文章，你不可能手工建几百个文件夹。把文件夹名写成方括号包起来的 [slug]，就得到一个「占位」文件夹——里面任何值都进同一个文件。slug 是行业里对「网址里那一段用来标识内容的短名字」的叫法。

app/blog/[slug]/page.tsx   # → /blog/任意值 都进这个文件

// 写法一（推荐）：用官方命令生成的类型 helper
// 先在终端跑一次 npx next typegen，它会生成 PageProps 这个全局类型
// app/blog/[slug]/page.tsx
export default async function Page(props: PageProps<"/blog/[slug]">) {
  const { slug } = await props.params; // 必须先 await
  return <h1>文章：{slug}</h1>;
}

// 写法二：手写类型，效果一样，不依赖 typegen
// app/blog/[slug]/page.tsx
export default async function Post({
  params,
}: {
  params: Promise<{ slug: string }>; // 注意是 Promise，不是对象
}) {
  const { slug } = await params; // /blog/hello 就拿到 slug = "hello"
  return (
    <main>
      <h1>文章：{slug}</h1>
      <p>真实项目里，这里用 slug 去数据库查文章正文。</p>
    </main>
  );
}

为什么会有这个改动？因为 Next.js 想让「取参数」和「取数据」的写法统一——两者都是「要等一下才有值」，那就用同一种语法（await）表达。代价是所有旧代码都要改一遍，这也是 16 版最集中的升级工作量。

分组：加一对括号，只归类、不进网址

app/
├── (marketing)/
│   ├── about/page.tsx          # → /about（括号不出现在网址里）
│   └── pricing/page.tsx        # → /pricing
└── (admin)/
    └── dashboard/page.tsx      # → /dashboard

用途是给不同板块套不同的外壳：营销页一个 layout、后台另一个 layout，而网址依然干净，不会多出 /marketing/about 这种前缀。

页面跳转的三件套

详情页的两个搭档：找不到就 404，找得到就提前生成

动态参数能接住任意网址，但用户可能乱输一个不存在的。这时要友好地显示 404，而不是让页面崩掉。另一个优化是：如果文章列表在构建时就是已知的，可以提前把页面生成好，用户打开就是秒开的静态页。

// app/blog/[slug]/page.tsx —— 404 兜底 + 预生成，一次配齐
import { notFound } from "next/navigation";

const posts: Record<string, string> = {
  "hello-nextjs": "欢迎来到 Next.js 的世界…",
  "first-deploy": "记录第一次上线的心情…",
};

// 构建时把这两篇提前生成好：用户打开就是秒开的静态页
export function generateStaticParams() {
  return Object.keys(posts).map((slug) => ({ slug }));
}

export default async function Post({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;      // 16 版：先 await
  const body = posts[slug];
  if (!body) notFound();              // 乱输的 slug 进 404，不炸站
  return (
    <main>
      <h1>{slug}</h1>
      <p>{body}</p>
    </main>
  );
}

全站 404 页：not-found.tsx

上一节的 error.tsx 管的是「代码报错」，而 notFound() 触发的 404 归 not-found.tsx 管。放一个在 app/ 根目录，全站乱输网址都有体面提示：

// app/not-found.tsx —— 全站 404，先有它再谈体验
import Link from "next/link";

export default function NotFound() {
  return (
    <main>
      <h1>404 · 页面去火星了</h1>
      <p>地址可能输错了，或者内容被搬走了。</p>
      <Link href="/">← 回首页</Link>
    </main>
  );
}

三个「兜底文件」的分工，别混

09取数据：一个 async 函数就够

先破一个过时的印象：取数据不用 useEffect 了

如果你看过早几年的 React 教程，取数据的标准写法是一长串：先声明一个装数据的变量、再声明一个装「加载中」的变量，然后在 useEffect（React 里「页面加载后要做的事」的钩子）里发请求，最后还要处理依赖警告。二十行起步。

在 Next.js 的服务端组件里，这一整套都不需要：组件函数自己可以是异步的，直接 await 结果就用。

// app/blog/page.tsx —— 整个函数是 async 的，这就是服务端组件的特权
async function getPosts() {
  const res = await fetch("https://jsonplaceholder.typicode.com/posts?_limit=5");
  if (!res.ok) throw new Error("文章加载失败");
  return res.json();
}

export default async function Blog() {
  const posts = await getPosts();  // 服务端拼好 HTML 才发给浏览器
  return (
    <main>
      <h1>博客列表</h1>
      <ul>
        {posts.map((p: { id: number; title: string }) => (
          <li key={p.id}>{p.title}</li>
        ))}
      </ul>
    </main>
  );
}

// 对照：老的客户端写法（需要交互的搜索框才这么写）
"use client";
import { useState, useEffect } from "react";

export default function Posts() {
  const [posts, setPosts] = useState([]);
  const [loading, setLoading] = useState(true);
  useEffect(() => {
    fetch("/api/posts")
      .then((r) => r.json())
      .then((d) => { setPosts(d); setLoading(false); });
  }, []);
  if (loading) return <p>加载中…</p>;   // 加载态还得自己画
  return <ul>{posts.map((p) => <li key={p.id}>{p.title}</li>)}</ul>;
}

缓存：默认不缓存了，要缓存得自己说

// 实时数据：每次请求都去取最新的（多数动态数据的正确选择）
const res = await fetch(url, { cache: "no-store" });

// 明确要缓存：告诉 Next.js 去用它自己的服务端缓存
const res3 = await fetch(url, { cache: "force-cache" });

// 折中：最多缓存 60 秒，之后后台悄悄更新（把旧的先给你，同时去取新的）
const res2 = await fetch(url, { next: { revalidate: 60 } });

需要交互的数据，还是放客户端

搜索框、筛选器这类「用户一动就要变」的地方，仍然用老办法（useEffect + fetch），或者用专门管这件事的库。下面那段代码里的「防抖」是这里唯一的新词：它指「用户停下来之后再发请求」——人连着敲字时只算最后一次，而不是每敲一下都打一次接口。原则一句话：首屏要展示的数据放服务端，需要即时交互的数据放客户端。

"use client"; // 客户端搜索框：输入即筛选，必须跑在浏览器
import { useState, useEffect } from "react";

export default function SearchBox() {
  const [q, setQ] = useState("");
  const [list, setList] = useState<string[]>([]);

  useEffect(() => {
    if (!q) { setList([]); return; }
    const t = setTimeout(async () => {
      const res = await fetch(`/api/search?q=${q}`);
      const data = await res.json();
      setList(data.items);
    }, 300);                      // 防抖 300ms：别每敲一个字母就请求一次
    return () => clearTimeout(t); // 清掉上一次的定时器
  }, [q]);

  return (
    <div>
      <input value={q} onChange={(e) => setQ(e.target.value)} placeholder="搜点什么…" />
      <ul>
        {list.map((item) => (
          <li key={item}>{item}</li>
        ))}
      </ul>
    </div>
  );
}

放进哪一边：一张决定表

10进阶三件套：写操作、接口、请求拦截

学会这三样，你就能独立做完一个带写操作的完整站点。

一、Server Actions：表单不用再写接口了

先讲它是什么：一个写在服务端的普通函数，函数顶部加一行 "use server"，然后表单可以直接把它当成提交目标。「Action」在这里就是「提交时要做的那件事」。

对比一下省了什么：老写法要前端发请求 → 后端接口接住 → 校验 → 写库，前后两个文件、两次数据搬运。现在一个文件、一个函数。

// app/guestbook/actions.ts —— 服务端函数
"use server";
export async function addMessage(formData: FormData) {
  const text = formData.get("text");
  // 这里可以直接写数据库，密钥不会泄露到浏览器
  console.log("收到留言：", text);
}

// app/guestbook/page.tsx —— 表单直接绑定它
import { addMessage } from "./actions";

export default function Guestbook() {
  return (
    <form action={addMessage}>
      <input name="text" placeholder="说点什么…" />
      <button type="submit">留言</button>
    </form>
  );
}

写完之后页面还是旧的？用 revalidatePath

Server Action 写完数据库后，页面可能还在显示缓存的旧内容。要告诉 Next.js「这一页脏了，重做一份」：

"use server";
import { revalidatePath } from "next/cache";

export async function addMessage(formData: FormData) {
  const text = formData.get("text");
  // …把 text 写入数据库…
  revalidatePath("/guestbook"); // 留言板页立即更新，不用等缓存过期
}

二、Route Handlers：正经写一个 JSON 接口

在 app/api/ 下面建文件夹，里面放一个叫 route.ts 的文件，导出 GET、POST 这样的函数——它就变成了标准接口，可以被小程序、手机 App 或第三方调用。

// app/api/hello/route.ts —— 访问 /api/hello 得到 JSON
import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ message: "你好，我是 Next.js 接口" });
}

export async function POST(request: Request) {
  const body = await request.json();
  return NextResponse.json({ received: body });
}

三、请求拦截：middleware.ts 已经改名叫 proxy.ts

// proxy.ts —— 放在项目根目录（和 app/ 同级）
// 保护 /dashboard：没登录就放行到登录页
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function proxy(request: NextRequest) {
  const loggedIn = request.cookies.get("token");
  if (!loggedIn && request.nextUrl.pathname.startsWith("/dashboard")) {
    return NextResponse.redirect(new URL("/login", request.url));
  }
  return NextResponse.next(); // 放行
}

// 只对 /dashboard 开头的路径生效；不写 matcher 会对每个请求都跑
export const config = { matcher: ["/dashboard/:path*"] };

三件套怎么选

流式渲染：先出壳、再填肉

页面里有的部分快、有的部分慢（比如评论区要查数据库）。别让慢的拖住整页——用 Suspense 包住慢的那块，快的先显示，慢的到了自动补上。

// app/blog/[slug]/page.tsx —— 正文秒开，评论慢慢到
import { Suspense } from "react";

export default async function Post(props: PageProps<"/blog/[slug]">) {
  const { slug } = await props.params;   // 16 版：先 await
  return (
    <main>
      <h1>{slug}</h1>
      <p>正文内容（快的，先出）</p>
      <Suspense fallback={<p>评论加载中…</p>}>
        <Comments slug={slug} />{/* 慢的组件，后到 */}
      </Suspense>
    </main>
  );
}

async function Comments({ slug }: { slug: string }) {
  await new Promise((r) => setTimeout(r, 2000)); // 模拟慢查询
  return <p>{slug} 的评论区（2 秒后出现）</p>;
}

11把零件拼成一个站：三个练习和一条路线

前面每一节给的都是零件。这一节把它们拼起来。建议按顺序做三个练习，每个只比上一步多一个能力。

练习一：个人博客（只读——先跑通路由和数据）

// app/blog/page.tsx —— 列表页骨架（先用假数据，跑通再说）
import Link from "next/link";

const posts = [
  { slug: "hello-nextjs", title: "你好，Next.js" },
  { slug: "my-first-deploy", title: "第一次部署上线" },
  { slug: "server-components", title: "搞懂服务端组件" },
];

export const metadata = { title: "博客 | 我的小站" };

export default function Blog() {
  return (
    <main>
      <h1>博客</h1>
      <ul>
        {posts.map((p) => (
          <li key={p.slug}>
            <Link href={`/blog/${p.slug}`}>{p.title}</Link>
          </li>
        ))}
      </ul>
    </main>
  );
}

配套的详情页用第 08 节那份 [slug]/page.tsx（含 notFound() 和 generateStaticParams()）。做完你会有：列表、详情、404 兜底、预生成。注意 params 必须 await。

练习二：留言板（读写闭环——加一个 Server Action）

// app/guestbook/page.tsx —— 读 + 写同页
import { addMessage } from "./actions";

const messages = ["第一条留言：这个网站真快！", "第二条：学会了文件即路由"];

export default function Guestbook() {
  return (
    <main>
      <h1>留言板</h1>
      <ul>
        {messages.map((m, i) => (
          <li key={i}>{m}</li>
        ))}
      </ul>
      <form action={addMessage}>
        <input name="text" placeholder="说点什么…" />
        <button type="submit">留言</button>
      </form>
    </main>
  );
}

配套的 app/guestbook/actions.ts 用第 10 节那份（含 revalidatePath）。这一步之后你就有了「读 + 写」的完整闭环。

练习三：待办清单（增删改——第一次亲手管状态）

前两个练习都是服务端为主，这个专练客户端。顺手理解一件事：状态就是「会变的记忆」。

"use client"; // 待办清单：全是点击和输入，必须是客户端组件
import { useState } from "react";

type Todo = { id: number; text: string; done: boolean };

export default function Todos() {
  const [todos, setTodos] = useState<Todo[]>([]);
  const [input, setInput] = useState("");

  function add() {
    if (!input.trim()) return; // 空输入直接忽略
    setTodos([...todos, { id: Date.now(), text: input, done: false }]);
    setInput("");
  }
  function toggle(id: number) {
    setTodos(todos.map((t) => (t.id === id ? { ...t, done: !t.done } : t)));
  }
  function remove(id: number) {
    setTodos(todos.filter((t) => t.id !== id));
  }

  return (
    <main>
      <h1>我的待办</h1>
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        placeholder="输入后点新增"
      />
      <button onClick={add}>新增</button>
      <ul>
        {todos.map((t) => (
          <li key={t.id}>
            <span onClick={() => toggle(t.id)}>
              {t.done ? "✅ " : "⬜ "}
              {t.text}
            </span>
            <button onClick={() => remove(t.id)}>删</button>
          </li>
        ))}
      </ul>
      <p>共 {todos.length} 项，已完成 {todos.filter((t) => t.done).length} 项</p>
    </main>
  );
}

合体：把三个练习拼成一个站

app/
├── (marketing)/          # 营销页组：网址里看不到括号
│   ├── page.tsx            # → / 首页：自我介绍 + 三个入口
│   ├── about/page.tsx      # → /about
│   └── layout.tsx          # 营销页专用外壳
├── (app)/                # 应用页组：后台、设置
│   ├── dashboard/page.tsx  # → /dashboard
│   └── layout.tsx          # 带侧边栏的外壳
├── blog/
│   ├── page.tsx            # → /blog 列表
│   └── [slug]/page.tsx    # → /blog/任意值 详情
├── guestbook/            # 留言板：page.tsx + actions.ts
├── todos/page.tsx        # 待办：客户端组件
├── api/hello/route.ts    # JSON 接口
└── layout.tsx            # 根外壳：导航、字体、全局样式
components/                   # 跨页面复用的 UI（按钮、卡片）
lib/                          # 工具函数、数据库连接
public/                       # 静态资源

练习路线：每一步都是上一步的自然延伸

七条军规，越早养成越省事

提交代码前的自查七问

12部署上线：推代码就是上线

代码只在自己电脑上跑不叫作品，别人能打开才叫上线。这一节给你两条路，先走快的那条。

上线前，本地先过三关

# 第一关：生产构建能不能过
npm run build
# 期望看到 Compiled successfully / Generating static pages
# 报错就从第一条红色错误开始修，多半是类型问题或 params 没 await

# 第二关：以生产模式跑起来，亲手点一遍
npm start
# 打开 http://localhost:3000 验收

# 第三关：确认没有把测试地址、私钥硬编码进代码（搜一遍再上线）

方案 A：Vercel 一键上线（新手首选）

方案 B：自己服务器 / Docker 部署

公司内网、有特殊合规要求时用。核心只有三步：

npm run build     # 在服务器上打包
npm start         # 启动生产服务，默认 3000 端口
# 再配一个反向代理（Nginx / Caddy）把域名指过来，并加上 HTTPS

环境变量：密钥怎么放才不泄露

# .env.production —— 生产环境的密钥放这里，不进 git
DATABASE_URL="postgresql://..."
NEXT_PUBLIC_SITE_URL="https://mysite.com"

两条路怎么选

上线后第一件事：看日志

规矩一句话：页面出错先看日志第一行，再回本地复现，别靠猜。

绑定自己的域名

13常见坑与报错速修

新手九成的卡点集中在这一张表里。按报错查，不要从第一条开始读全文。

按现象查：十个高频坑

从旧版 pages/ 迁移过来时的水土不服

如果你在别人的老项目里看到下面这些名字，要知道它们已经被取代了。别逐行翻译，重写更顺：

大版本升级：用官方工具，别手改版本号

# 1. 先提交干净代码（留一份能回滚的档）
git add -A && git commit -m "before upgrade"

# 2. 跑官方升级工具，它会自动改掉大部分机械性变动
#    （注意：它不会跑全部迁移，同步 params 那类还要单独跑一次 async 迁移）
npx @next/codemod@canary upgrade latest

# 3. 过一遍官方升级指南里的破坏性改动，再 build 验证
npm run build

英文报错高频五句

14命令小抄

贴在显示器边上，忘了就来翻。

命令

文件约定 → 网址

数据、跳转与写操作

环境变量

15术语对照表

遇到看不懂的词回来查。第三列是为什么重要、什么时候用、别当什么用——比一句翻译有用得多。

99一句话总结

带走这三句

1. 文件夹就是网址——建页面先建文件夹，里面必须有 page.tsx。
2. 默认放服务端，交互才下沉——分不清时先全写服务端，报错再拆出 "use client"。
3. 先 build 再上线——本地 build 过了，上线就稳了一大半。

现在就动手

打开终端，跑这两行，把第 05 节的两个页面亲手敲出来：

npx create-next-app@latest my-app
cd my-app && npm run dev

遇到红色报错，把完整报错连同你用的 Next.js 版本一起发给 AI 助手。你已经学会了最难的那一步：开始。

练习：把这个教程变成你自己的

下面这份提问模板可以直接复制去问 AI，它保证 AI 按 16 版的写法回答你（尤其是 await params 和 proxy 这两处）：

我想用 Next.js（App Router，v16.3）做一个【博客 / 留言板 / 待办（三选一）】。
请按以下要求生成代码：
1. 文件放在 app/xxx/page.tsx，TypeScript + Tailwind
2. 服务端组件优先，只有交互部分用 "use client"
3. 动态路由的 params 必须按 v16 写法 await，不要给同步写法
4. 如果要写请求拦截，用 proxy.ts 而不是 middleware.ts
5. 每页导出 metadata 标题
6. 告诉我每一步在终端敲什么命令验证
下面是我的报错（如有，粘贴完整的红色文字）：【粘贴处】

97新手最常问的八个问题

98参考来源与证据边界

本文的关键事实均在 2026-09-13 逐条核对过以下来源：

这 4 个链接建议收藏