Next.js 深度学习指南目录第一部分：学习路线与前提第二部分：Getting Started 全部 19 页精读

基于 Next.js 官方文档（nextjs.org/docs）全部 426 个 MDX 文件逐一阅读 + 源码 1601 个 TypeScript 文件深度分析文档版本：2026 年 5 月，Next.js 16.x（App Router + Pages Router）本指南覆盖：Getting Started (19)、Guides (63)、API Reference (~160)、Pages Router (~195)、Architecture (5)、Community (3)

第一部分：学习路线与前提
第二部分：Getting Started 全部 19 页精读
第三部分：Guides 全部 63 页精读
第四部分：API Reference 全部 ~160 页总览
第五部分：Pages Router 文档总览
第六部分：Architecture 与 Community 文档
第七部分：源码架构深度分析（1601 文件）
第八部分：五阶段学习路线与实战项目

第一部分：学习路线与前提

前提知识

技能	要求	说明
HTML/CSS	熟练	DOM、Flexbox/Grid、响应式
JavaScript ES6+	熟练	async/await、解构、Promise、模块
TypeScript	基础	类型注解、接口、泛型
React 18+	掌握	Hooks、Suspense、Context、use API
Node.js	基础	npm/pnpm、HTTP、文件系统
HTTP 协议	基础	状态码、Headers、缓存

总览学习路线

阶段一(1-2周)         阶段二(2-3周)         阶段三(2-3周)
Getting Started      核心概念深入           高级特性
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│安装/项目结构   │   │RSC/客户端组件 │   │Streaming     │
│布局/页面/路由  │→  │数据获取/变更  │→  │PPR/缓存      │
│CSS/图片/字体   │   │缓存/重验证   │   │Proxy/认证    │
│Link/导航      │   │错误处理      │   │i18n/部署     │
└──────────────┘   │Route Handler │   │测试/安全     │
                    │Metadata/SEO │   └──────────────┘
                    └──────────────┘
                           ↓
阶段四(3-4周)         阶段五(2-4周)
源码阅读              实战项目
┌──────────────┐   ┌──────────────┐
│CLI→Server    │   │博客系统      │
│App Render    │   │全栈CRUD      │
│Build管线     │→  │电商Dashboard │
│Client运行时   │   │开源贡献      │
│Turbopack/Rust│   └──────────────┘
└──────────────┘

第二部分：Getting Started 全部 19 页精读

1. Installation（安装）

核心要点：

pnpm create next-app@latest 快速创建（推荐 pnpm）
默认启用：TypeScript、Tailwind CSS、ESLint、App Router、Turbopack
系统要求：Node.js 20.9+，浏览器 Chrome 111+ / Edge 111+ / Firefox 111+ / Safari 16.4+
创建时可选择推荐默认或自定义（TypeScript/linter/Tailwind/src目录/App Router/别名/AGENTS.md）

手动安装：

pnpm i next@latest react@latest react-dom@latest
App Router 使用 React canary 版本（包含所有稳定的 React 19 更改）
脚本：next dev（Turbopack 默认）、next build、next start

关键配置：

app/layout.tsx：根布局（必需，含 <html> 和 <body>）
app/page.tsx：首页
public/：静态资源目录
tsconfig.json 中 baseUrl 和 paths 设置路径别名
16 版起 next build 不再自动运行 linter

2. Project Structure（项目结构）

顶层文件夹：app（App Router）、pages（Pages Router）、public（静态资源）、src（可选源码目录）

顶层文件：

next.config.js — 配置文件
instrumentation.ts — OpenTelemetry 和 Instrumentation
proxy.ts — 请求代理（原 middleware.ts）
.env / .env.local / .env.production / .env.development — 环境变量

路由特殊文件（优先级从高到低）：

文件	作用
`layout.js`	共享布局 UI
`template.js`	每次导航重新挂载的布局
`error.js`	错误边界 UI（必须是 Client Component）
`loading.js`	加载骨架屏（自动包裹 Suspense）
`not-found.js`	404 UI
`page.js`	路由页面 UI
`route.js`	API 端点
`default.js`	并行路由回退页面

组件渲染层级：layout → template → error（Error Boundary）→ loading（Suspense）→ not-found → page 或嵌套 layout

路由模式：

嵌套路由：文件夹嵌套 = URL 嵌套
动态路由：[slug]（单参数）、[...slug]（捕获所有）、[[...slug]]（可选捕获所有）
路由组：(group) — 不影响 URL，用于组织代码
私有文件夹：_folder — 不参与路由
并行路由：@slot — 命名插槽
拦截路由：(.)folder / (..)folder / (...)folder

元数据文件约定：favicon.ico、icon、apple-icon、opengraph-image、twitter-image、sitemap.xml、robots.txt

项目组织策略：

项目文件放在 app 外的共享文件夹
项目文件放在 app 内的顶层文件夹
按功能/路由拆分项目文件
使用路由组组织路由，不影响 URL
创建多个根布局

3. Layouts and Pages（布局与页面）

核心概念：

page.tsx 定义路由 UI，layout.tsx 定义共享 UI
布局在导航时保持状态、不重新渲染
根布局必须包含 <html> 和 <body> 标签
子目录的 layout 自动嵌套在父 layout 内

动态路由段：

[segmentName]：通过 params prop 访问（Promise 类型）
generateStaticParams 可预生成静态路径

搜索参数：

Server Component：searchParams prop（Promise，触发动态渲染）
Client Component：useSearchParams hook
优化：回调/事件中用 new URLSearchParams(window.location.search) 避免重渲染

Route Props Helpers（TypeScript 全局类型）：

PageProps<'/blog/[slug]'> — 页面组件 props
LayoutProps<'/dashboard'> — 布局组件 props（含命名插槽）
运行 next dev、next build 或 next typegen 时生成

4. Linking and Navigating（链接与导航）

导航四大机制：

服务端渲染：预渲染（构建时）vs 动态渲染（请求时）
预取：<Link> 进入视口或悬停时自动预取；静态路由全量预取，动态路由部分预取
流式渲染：loading.tsx 创建 Suspense 边界，服务器逐步发送 HTML
客户端转场：保持共享布局，动态替换内容，无全页刷新

导航变慢的原因与对策：

动态路由无 loading.tsx → 添加 loading.tsx
动态段无 generateStaticParams → 添加以启用静态生成
慢网络 → 使用 useLinkStatus hook 显示即时反馈
Hydration 未完成 → 减小 JS 体积，使用 @next/bundle-analyzer
禁用预取 → 改为悬停时预取（onMouseEnter 设置 prefetch）

原生 History API 集成：

window.history.pushState(null, '', url) — 添加历史条目
window.history.replaceState(null, '', url) — 替换当前条目
与 usePathname、useSearchParams 自动同步

5. Server and Client Components（服务端与客户端组件）

这是 Next.js 最核心的概念。

Server Components（默认）：

在服务器渲染，不发送 JS 到客户端
可直接访问数据库、API 密钥、文件系统
减少客户端 JS，改善 FCP
渲染为 RSC Payload（紧凑的二进制表示）

Client Components（'use client'）：

需要 useState/useEffect/onClick 等交互
需要浏览器 API（localStorage, window）
声明在文件顶部，影响该文件所有导入和子组件

渲染流程：

服务端：SC 渲染为 RSC Payload → CC + RSC Payload 预渲染 HTML
客户端首次加载：HTML 即时预览 → RSC Payload 协调组件树 → JS Hydration
后续导航：仅获取 RSC Payload（rsc:1 header），无 HTML 传输

组合模式：

SC 通过 children prop 传递给 CC（<Modal><Cart /></Modal>）
Context Provider 必须是 CC，但可包裹 SC（provider 放 layout 中）
第三方组件无 'use client'？创建包装 CC：export default Carousel

环境安全：

server-only 包：防止服务端代码泄露到客户端（构建时报错）
client-only 包：标记仅客户端模块
仅 NEXT_PUBLIC_ 前缀变量包含在客户端 bundle 中

最佳实践：将 'use client' 放在尽可能低的组件层级，大部分 UI 保持为 SC。

6. Fetching Data（数据获取）

服务端获取：

fetch API：组件设为 async，await fetch 调用；相同请求自动去重
ORM/数据库：直接查询，凭证不含在客户端 bundle 中
默认不缓存，使用 'use cache' 指令缓存

流式加载：

loading.js：页面级流式（自动包裹 Suspense）
<Suspense>：组件级流式（推荐，更精细控制）
布局中未缓存数据（cookies/headers）不会触发同路由段的 loading.js

客户端获取：

React use API：SC 传 Promise 到 CC，CC 用 use() 读取
SWR / React Query：社区库

数据获取模式：

顺序：一个请求依赖另一个的数据 → 用 Suspense 避免阻塞
并行：Promise.all([getData1(), getData2()]) 同时发起
共享：React.cache() 去重 + Context Provider 跨组件共享 Promise

7. Mutating Data（数据变更）

Server Functions / Server Actions：

'use server' 指令标记（文件级或函数级）
通过 POST 方法调用，必须是 async
始终验证身份和权限

调用方式：

表单：<form action={serverAction}> — 自动获取 FormData
事件处理器：onClick={async () => await serverAction()}
useEffect：组件挂载时用 startTransition 触发

变更后更新：

refresh() — 刷新当前页面（不重验证标签数据）
revalidatePath('/path') — 重验证特定路径
revalidateTag('tag') — 按标签重验证（stale-while-revalidate）
updateTag('tag') — 立即过期（read-your-own-writes）
redirect('/path') — 重定向（抛出控制流异常，之后代码不执行）

Cookies 操作：SC Action 中可 get/set/delete cookies，设置/删除后 Next.js 重渲染当前页面。

安全：Server Functions 可通过 POST 直接访问，不仅限于 UI 调用。必须在每个函数内验证认证和授权。

8. Caching（缓存）

Cache Components（新模型）：

next.config.ts 中 cacheComponents: true 启用
'use cache' 指令缓存函数或组件
参数和闭包值自动成为缓存键

两个层级：

数据级缓存：缓存获取数据的异步函数（独立于 UI）
UI 级缓存：缓存整个组件/页面/布局

cacheLife() 预设配置：

配置	stale	revalidate	expire
seconds	0	1s	60s
minutes	5m	1m	1h
hours（默认）	5m	1h	1d
days	5m	1d	1w
weeks	5m	1w	30d
max	5m	30d	无限

短生命缓存：seconds 或 expire < 5min 时自动排除在预渲染外，成为动态空洞。

运行时 API：cookies/headers/searchParams/params 需包裹在 <Suspense> 中。可提取运行时值传给缓存函数作为参数（成为缓存键）。

非确定性操作：Math.random()/Date.now() 需调用 connection() 延迟到请求时，或缓存结果让所有用户看到相同值。

Partial Prerendering (PPR)：

静态外壳（布局/导航/Suspense fallback）构建时预渲染
动态部分请求时流式加载
未包裹 Suspense 的未缓存数据访问会报错

9. Revalidating（重验证）

时间重验证：cacheLife('hours') — 自动按时间刷新

按需重验证：

API	语义	使用场景	可用位置
`revalidateTag(tag, 'max')`	stale-while-revalidate	博客、产品目录	Server Actions + Route Handlers
`updateTag(tag)`	立即过期	用户自己的变更	仅 Server Actions
`revalidatePath('/path')`	按路径重验证	不知道标签时	Server Actions + Route Handlers

cacheTag()：给缓存打标签，配合 revalidateTag/updateTag 按需失效。

最佳实践：优先用标签重验证（精确），路径重验证作为兜底。

10. Error Handling（错误处理）

预期错误：

useActionState hook 处理表单验证错误 — 作为返回值，不用 try/catch
Server Component 中检查 res.ok 条件渲染
notFound() 函数 + not-found.js 文件显示 404

未捕获异常：

error.js 创建错误边界（必须是 Client Component）
props：error（含可选 digest）、unstable_retry（重试函数）
错误向上冒泡到最近的父错误边界
unstable_catchError 可在组件树任意位置创建错误边界

全局错误：global-error.js 处理根布局级别错误（必须定义 <html> 和 <body>）

事件处理器错误：错误边界不捕获，需手动 try/catch + useState。startTransition 中未处理的错误会冒泡到错误边界。

11. CSS（样式）

5 种样式方案（推荐顺序）：

Tailwind CSS — 安装 tailwindcss @tailwindcss/postcss，添加 PostCSS 插件，在全局 CSS 中 @import 'tailwindcss'
CSS Modules — .module.css 文件，生成唯一类名，防止命名冲突
全局 CSS — 在根布局导入，适用于所有路由
外部样式表 — 从 node_modules 导入
Sass — .scss/.sass 文件
CSS-in-JS — 需要 Client Component

CSS 顺序：取决于代码中的导入顺序。建议将 CSS 导入集中在单一入口文件，关闭自动排序导入的 linter 规则。

开发 vs 生产：开发用 Fast Refresh 即时更新；生产所有 CSS 合并为最小化的 .css 文件，按路由代码分割。

12. Image Optimization（图片优化）

next/image 特性：

自动选择合适尺寸和现代格式（WebP）
防止布局偏移（CLS）
原生浏览器懒加载 + 可选模糊占位符
远程图片按需调整大小

本地图片：存放 public/ 目录或静态导入（自动推断宽高和 blurDataURL）

远程图片：需手动提供 width/height 或使用 fill；必须在 next.config.js 的 remotePatterns 中配置允许的来源

动态导入图片：SC 中用 await import() 可获取自动尺寸，路径需包含静态前缀

13. Font Optimization（字体优化）

next/font 特性：

构建时下载字体，自托管，零外部请求
零布局偏移
支持 Google Fonts（next/font/google）和本地字体（next/font/local）
推荐使用可变字体（Variable Fonts）

使用方式：导入字体函数，配置选项，通过 className 或 style 应用到元素。全局使用时添加到根布局的 <html> 元素。

14. Metadata and OG Images（元数据与 OG 图片）

三种方式：

静态 metadata 对象导出
动态 generateMetadata 函数（接受 params/searchParams）
文件约定（favicon.ico、opengraph-image.tsx 等）

Streaming Metadata：metadata 单独流式传输，不阻塞 UI。对 bot 禁用（通过 User-Agent 检测），可用 htmlLimitedBots 配置。

动态 OG 图片：ImageResponse 构造器 + JSX/CSS 生成；支持 flexbox 和常见 CSS，不支持 grid。

数据去重：React.cache() 包装数据获取函数，metadata 和页面共享同一请求。

15. Route Handlers（路由处理器）

约定：app/**/route.ts 文件，不能与 page.tsx 同路由段

HTTP 方法：GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS（不支持的返回 405）

缓存：默认不缓存；GET 可通过 export const dynamic = 'force-static' 启用缓存

Cache Components 模式：

静态（无运行时数据）→ 构建时预渲染
动态（Math.random()/headers()）→ 请求时渲染
缓存（'use cache' 在辅助函数中）→ 可预渲染

Route Context Helper：RouteContext<'/users/[id]'> 全局 TypeScript 类型

16. Proxy（代理，原 Middleware）

定义：请求完成前执行的代码，可重写/重定向/修改 Headers/直接响应

文件：项目根目录 proxy.ts（每个项目只能有一个）

使用场景：A/B 测试、权限重定向、修改 Headers。不适合慢数据获取。

导出：命名导出 proxy 或 default export + config.matcher 过滤路径

注意：fetch 的 cache/revalidate/tags 选项在 Proxy 中无效

17. Deploying（部署）

方式	功能	说明
Node.js 服务器	完整	`next build && next start`
Docker	完整	推荐 `output: 'standalone'`
静态导出	有限	`output: 'export'`，不支持服务端功能
适配器	取决于平台	Vercel（验证）、Bun（验证）、Cloudflare/Netlify（开发中）

18. Upgrading（升级）

Next.js 16.1.0+：pnpm next upgrade
更早版本：npx @next/codemod@canary upgrade latest
Canary 版本：pnpm add next@canary
Canary 新特性：forbidden()、unauthorized() 函数及对应文件约定

第三部分：Guides 全部 63 页精读

核心指南

AI Coding Agents

版本匹配文档捆绑在 node_modules/next/dist/docs/
AGENTS.md 指导 AI agent 使用捆绑文档而非过期训练数据
Next.js 16.3+ 通过 next dev 自动生成

Analytics（分析）

Web Vitals：TTFB、FCP、LCP、FID、CLS、INP
instrumentation-client.js 客户端 Instrumentation
useReportWebVitals hook 测量性能指标
需创建单独的 Client Component 调用 hook

Authentication（认证）— 最重要的安全指南

三层模型：

认证：验证用户身份（Server Actions + useActionState + Zod 验证）
会话管理：无状态（JWT + Cookie，推荐 Jose 库）或数据库会话
授权：控制访问权限

安全模式：

Proxy 乐观检查（基于 Cookie，快速但不完整）
Data Access Layer (DAL)：集中化数据访问和授权逻辑，verifySession() + React.cache()
Data Transfer Objects (DTO)：只返回必要数据字段

Cookie 安全选项：HttpOnly、Secure、SameSite: 'lax'、Max-Age、Path

推荐库：Auth0、Better Auth、Clerk、NextAuth.js、Supabase 等

Backend for Frontend（BFF 模式）

Route Handlers 作为公开 HTTP 端点
支持所有 Content-Type（JSON、XML、图片、文件）
内容协商：通过 rewrites + Accept header 匹配
请求体消费：.json()、.formData()、.text()
代理后端 API：验证 + 转发
安全：速率限制、负载验证、访问控制

Caching (Previous Model)（旧缓存模型）

Fetch 默认不缓存，cache: 'force-cache' 启用
unstable_cache 缓存非 fetch 函数
Route Segment Config：dynamic、fetchCache、revalidate
按需重验证：revalidateTag() + revalidatePath()
React cache() 请求去重

CDN Caching（CDN 缓存）

静态页面：s-maxage=31536000
ISR 页面：s-maxage={revalidate}, stale-while-revalidate
动态页面：private, no-cache, no-store, max-age=0, must-revalidate
必须保留 rsc header 和 _rsc 参数作为缓存键

CI Build Caching（CI 构建缓存）

缓存 .next/cache 目录
支持平台：Vercel（自动）、CircleCI、Travis CI、GitLab CI、GitHub Actions、AWS CodeBuild 等

Content Security Policy（CSP）

Nonce 方案：Proxy 中生成 nonce → 注入 x-nonce header → 应用到 scripts/styles
SRI（实验性）：基于哈希，允许静态生成，性能更好
开发需 'unsafe-eval'

CSS-in-JS

支持：styled-jsx、styled-components、Chakra UI、MUI、Emotion、PandaCSS、StyleX 等
集成模式：Style Registry + useServerInsertedHTML hook

Custom Server（自定义服务器）

next 模块编程式启动
app.prepare() + app.getRequestHandler()
代价：失去自动静态优化和部分性能优化

Data Security（数据安全）

三种数据访问方式：

外部 HTTP API（零信任模型）
Data Access Layer（推荐新项目）
组件级访问（仅原型）

安全技术：

experimental_taintObjectReference/experimental_taintUniqueValue 防止数据泄露到客户端
server-only 包标记服务端模块
Server Actions 闭包变量自动加密
始终在 Server Actions/Route Handlers 中重新验证授权

Debugging（调试）

VS Code：launch 配置（客户端/服务端/全栈）
Chrome DevTools：--inspect flag
Firefox：Ctrl+Shift+I → Debugger

Deploying to Platforms（平台部署）

功能保真度 vs 性能保真度
Streaming 是 SC/PPR/Server Actions 的基础设施要求
共享缓存推荐用于 ISR/PPR/Cache Components
CDN 兼容性矩阵覆盖 Cloudflare/Akamai/AWS CloudFront/Fastly 等

Draft Mode（草稿模式）

Route Handler 中 draftMode().enable() 启用
强制每次请求获取新鲜结果，不保存到缓存
响应头：private, no-cache, no-store, max-age=0, must-revalidate

Environment Variables（环境变量）

加载顺序：process.env → .env.$(NODE_ENV).local → .env.local → .env.$(NODE_ENV) → .env
NEXT_PUBLIC_ 前缀内联到客户端 JS（构建时确定）
@next/env 包可在 Next.js 运行时外加载环境变量
$VARIABLE 自动引用其他变量
测试环境：.env.test 文件，不加载 .env.local

Forms（表单）

HTML <form action={serverAction}> 自动处理 FormData
.bind() 传递额外参数
客户端验证（HTML 属性）+ 服务端验证（Zod）
useActionState 显示错误状态和 pending 状态

How Revalidation Works（重验证工作原理）

HTML 和 RSC Payload 一起重验证保证一致性
显式标签：cacheTag() / fetch next.tags
软标签：从路由路径自动生成 _N_T_/...
多实例协调：updateTags() 写入共享存储 → refreshTags() 定期读取

ISR（增量静态再生）

无需全量重建更新静态内容
generateStaticParams() 预渲染已知路由
revalidate 选项控制时间重验证
dynamicParams 控制未知路由行为

Instant Navigation（即时导航）

缓存内容即时显示，动态内容在 Suspense fallback 后流式加载
unstable_instant 导出用于验证
DevTools 可视化切换

Instrumentation（Instrumentation）

instrumentation.ts 根目录文件
register() 函数：服务器启动时调用一次
必须在处理请求前完成
可按运行时导入代码（Node.js vs Edge）

Internationalization（国际化）

[lang] 动态路由段
Proxy 中检测 Accept-Language 自动重定向
字典文件管理翻译
generateStaticParams 生成静态语言路径
Server Component 中加载字典（不影响客户端 JS 体积）

进阶指南

JSON-LD（结构化数据）

XSS 防护：字符转义
dangerouslySetInnerHTML 安全模式

Lazy Loading（懒加载）

next/dynamic 动态导入（支持 SSR 选项）
React.lazy() + Suspense
Webpack magic comments 预加载

Local Development（本地开发）

Turbopack 默认 bundler
杀毒软件排除建议
性能优化技巧

MCP（Model Context Protocol）

AI Agent 集成
错误检测、实时状态查询

MDX

自定义组件、frontmatter
remark/rehype 插件

Memory Usage（内存使用）

堆分析策略
Source Map 控制

Migration Guides（迁移指南）

Create React App → Next.js
Vite → Next.js
Pages Router → App Router
迁移到 Cache Components

Multi-tenant（多租户）

子域名路由
共享布局

Multi-zones（多区域）

微前端架构
assetPrefix 配置

OpenTelemetry

自定义 spans
分布式追踪
Vercel 集成

Package Bundling（包打包）

@next/bundle-analyzer 分析
优化技术

PPR Platform Guide（PPR 平台指南）

静态外壳在 CDN 交付
动态流式内容
CDN 集成要求

Prefetching（预取）

自动预取（视口/悬停）
手动预取策略
客户端缓存 TTL

Preserving UI State（保持 UI 状态）

Cache Components + React Activity
表单状态持久化

Preventing Flash Before Hydration

内联脚本 + suppressHydrationWarning

Production Checklist（生产清单）

全面优化策略列表

PWA（渐进式 Web 应用）

Manifest 文件
推送通知
Service Worker

Public Static Pages（公开静态页面）

静态与缓存组件结合 Suspense

Redirecting（重定向）

redirect() / permanentRedirect() / useRouter / config

Rendering Philosophy（渲染哲学）

核心理念：静态与动态是一个光谱，不是二元选择
边界在组件级别，不是路由级别
功能保真度 vs 性能保真度
基础设施要求：Streaming + 缓存协调 + 缓存一致性

Sass

.scss/.sass 支持
sassOptions 配置
CSS Module 变量导出

Scripts（脚本）

next/script 组件
加载策略：beforeInteractive / afterInteractive / lazyOnload / worker
事件处理器：onLoad / onReady / onError

Self-Hosting（自托管）

反向代理（Nginx）处理安全
X-Accel-Buffering: no 支持 Streaming
自定义缓存处理器（Redis 等）
多实例：共享加密密钥 NEXT_SERVER_ACTIONS_ENCRYPTION_KEY
deploymentId 版本偏移保护
'use cache: remote' 跨实例共享缓存
refreshTags() 方法协调标签失效

Single-Page Applications（SPA）

React use() API
SWR 集成
浅层路由

Static Exports（静态导出）

output: 'export' 配置
支持 SC、CC、图片优化（自定义 loader）、Route Handlers（仅 GET）
不支持：动态路由无 generateStaticParams、Proxy、ISR、Draft Mode、Server Actions

Streaming（流式渲染）— 最重要的高级概念

两个并行流：

HTML 流：静态外壳 → Suspense fallback → 已解析组件 HTML + 内联 <script> 替换
组件载荷（RSC Payload）：嵌入 HTML 流中，用于 Hydration

静态外壳：Suspense 边界之前的所有内容，立即发送

页面级 vs 组件级：

loading.js：整页流式，不可预取
<Suspense>：组件级，独立解析，不互相阻塞

关键原则：将动态数据访问下推到真正需要的组件（不在 layout 中 await）

HTTP 契约：

流式开始后无法更改状态码（已发送 200）
notFound() 中流注入 <meta name="robots" content="noindex">
redirect() 变成客户端重定向
Metadata 在 bot 前阻塞解析，在浏览器中流式

基础设施影响：

Nginx：禁用 buffering
CDN：检查 chunked response 支持
Serverless：需显式启用 streaming（如 AWS Lambda）
压缩算法可能缓冲块
Safari/WebKit 缓冲前 1024 字节

Web Vitals 影响：TTFB↓ FCP↓（静态外壳立即发送），LCP 保持在 Suspense 外，CLS 用匹配尺寸的骨架屏，INP 通过选择性 Hydration 改善。

Testing（测试）

Jest：单元测试/快照测试
Vitest：单元测试（更快、Vite 兼容）
Playwright：E2E 测试（推荐）
Cypress：E2E + 组件测试
async SC 建议用 E2E 测试而非单元测试

View Transitions（视图转场）

实验性视图转场 API 支持

第四部分：API Reference 全部 ~160 页总览

Directives（指令，6 页）

指令	用途
`'use cache'`	缓存异步函数/组件；参数为缓存键；默认配置 stale:5m, revalidate:15m
`'use cache: private'`	访问运行时 API（cookies/headers）但结果仅在浏览器内存中，不持久化
`'use cache: remote'`	远程缓存（Redis/KV），跨实例共享，适合限速 API 和慢后端
`'use client'`	标记客户端组件边界，props 必须可序列化
`'use server'`	标记服务端函数，文件级或行内

Components（组件，6 页）

组件	关键 Props
`<Font>` (`next/font`)	src, weight, style, subsets, display, preload, variable
`<Form>`	action(string/function), replace, scroll, prefetch
`<Image>` (`next/image`)	src, alt, width, height, fill, loader, sizes, quality, placeholder, blurDataURL
`<Link>` (`next/link`)	href, replace, scroll, prefetch, onNavigate, transitionTypes
`<Script>` (`next/script`)	src, strategy(beforeInteractive/afterInteractive/lazyOnload/worker), onLoad/onReady/onError

File Conventions（文件约定，~32 页）

文件	Props/导出	关键行为
`page.js`	params(Promise), searchParams(Promise)	路由 UI，必须用 async/await 或 `use()`
`layout.js`	children, params	不重渲染，不能访问 searchParams
`loading.js`	无参数	自动包裹 Suspense
`error.js`	error, unstable_retry	必须 Client Component
`route.js`	request(NextRequest), context.params	HTTP handlers
`template.js`	children	导航时重新挂载
`not-found.js`	无	`notFound()` 触发
`default.js`	params(Promise)	并行路由硬导航回退
`proxy.js`	request(NextRequest)	请求前处理
`instrumentation.js`	register()	服务器启动调用
`instrumentation-client.js`	无	客户端 instrumentation
Dynamic Segments	`[slug]`, `[...slug]`, `[[...slug]]`	params 是 Promise
Intercepting Routes	`(.)`, `(..)`, `(...)`	拦截路由模式
Route Segment Config	dynamicParams, instant, maxDuration, preferredRegion, runtime	段级配置

Functions（函数，~39 页）

数据与缓存：

fetch() — Next.js 扩展 Web Fetch，自动去重
cacheLife() — 缓存生命周期配置
cacheTag() — 标记缓存数据
updateTag() — 立即过期标签
revalidateTag() — stale-while-revalidate 重验证
revalidatePath() — 按路径重验证
unstable_cache() — 缓存异步函数（旧 API）
unstable_noStore() — 退出缓存
connection() — 延迟到请求时

请求/响应：

cookies() — async，read/set/delete cookies
headers() — async，只读请求头
NextRequest — 扩展：nextUrl, cookies, geo
NextResponse — 扩展：headers/cookies 操作
after() — 响应发送后执行代码
userAgent() — 检测用户代理

导航：

redirect() — 服务端重定向
permanentRedirect() — 永久重定向（308/301）
notFound() — 渲染 not-found UI
forbidden() — 渲染 forbidden UI（canary）
unauthorized() — 渲染 unauthorized UI（canary）

元数据：

generateMetadata() — 动态元数据
generateStaticParams() — 预渲染路由
generateViewport() — 视口配置
generateImageMetadata() — 图片元数据
generateSitemaps() — 站点地图

Hooks：

useRouter() — 客户端路由（push/replace/refresh/back/forward/prefetch）
usePathname() — 当前路径
useParams() — 动态路由参数
useSearchParams() — 查询参数
useSelectedLayoutSegment() — 当前激活的布局段
useSelectedLayoutSegments() — 所有激活的布局段
useFormStatus() — 表单提交状态
useReportWebVitals() — 性能指标
useLinkStatus() — 链接导航状态
refresh() — 刷新当前路由

错误处理：

unstable_catchError() — 组件级错误边界

Config（配置，~63 页）

next.config.js 核心选项：

分类	选项
路由	basePath, trailingSlash, redirects, rewrites, headers, pageExtensions
构建	distDir, output('standalone'/'export'), compress, generateEtags
缓存	cacheComponents, cacheHandlers, cacheLife, incrementalCacheHandlerPath
图片	images(remotePatterns, deviceSizes, formats, minimumCacheTTL)
样式	sassOptions, cssChunking, inlineCss
性能	reactCompiler, poweredByHeader, httpAgentOptions
打包	webpack, turbopack, transpilePackages, serverExternalPackages
安全	serverActions, taint
开发	devIndicators, onDemandEntries, logging
资源	assetPrefix

CLI（3 页）

next dev / build / start / lint / telemetry / info / analyze / typegen / upgrade
create-next-app — 项目脚手架

Adapters（12 页）

适配器 API 用于非 Node.js 环境部署
配置、路由、PPR 实现、运行时集成、输出类型、测试

Edge Runtime（1 页）

Node.js API 子集，低延迟
用于 Proxy 和边缘函数

Turbopack（1 页）

Turbopack 配置参考

第五部分：Pages Router 文档总览

Pages Router 约 195 个 MDX 文件，是 Next.js 的传统路由系统。

核心差异（vs App Router）

特性	Pages Router	App Router
路由	`pages/` 目录	`app/` 目录
数据获取	getStaticProps/getServerSideProps/getInitialProps	async SC + fetch + use cache
组件模型	全部客户端组件	Server Components 默认
布局	`_app.js` + getLayout 模式	`layout.js` 嵌套布局
API 路由	`pages/api/`	`app/api/route.ts`
错误页面	`_error.js` + `404.js` + `500.js`	`error.js` + `not-found.js` + `global-error.js`
文档自定义	`_document.js`	根 `layout.js`

关键概念

数据获取：

getStaticProps — 构建时获取数据（SSG）
getStaticPaths — 动态路由预渲染（fallback: true/false/blocking）
getServerSideProps — 每次请求获取数据（SSR）
getInitialProps — 通用数据获取（不推荐）

渲染策略：

SSG + ISR：构建时 + 增量再生
SSR：每次请求渲染
CSR：客户端 useEffect/SWR
自动静态优化：无数据需求时自动静态化

路由：

文件系统路由（pages/about.js → /about）
动态路由（[id].js、[...slug].js）
API Routes（pages/api/）
浅层路由（shallow routing）

第六部分：Architecture 与 Community 文档

Architecture（5 页）

Accessibility（无障碍）

路由切换公告
ESLint jsx-a11y 插件
WCAG 支持

Fast Refresh（快速刷新）

热模块替换，保持组件状态
仅编辑导出 React 组件的文件时触发
错误恢复机制

Next.js Compiler（编译器）

基于 SWC（Rust），比 Babel 快 17 倍
v12 起默认启用
支持：Styled Components、Jest、Relay、React 属性移除、console 移除、装饰器、Emotion、压缩
模块转译、optimizePackageImports
SWC 插件（实验性）

Supported Browsers（浏览器支持）

Chrome 111+、Edge 111+、Firefox 111+、Safari 16.4+
Browserslist 配置
Polyfills：fetch、URL、Object.assign

Community（3 页）

Contribution Guide（贡献指南）

文件系统路由 + 两位数前缀
MDX 格式 + JSX 支持
<AppOnly> / <PagesOnly> 组件区分路由器
代码块：语言、文件名、语法高亮、行高亮
TS/JS 切换器模式

Rspack（社区集成）

使用 Rspack 打包的社区插件（实验性）

第七部分：源码架构深度分析（1601 文件）

整体统计

模块	文件数	占比
Server	539	33.7%
Build	265	16.6%
Client	190	11.9%
Shared	159	9.9%
Lib	133	8.3%
API	52	3.2%
Bundles	47	2.9%
其他	216	13.5%
总计	1601	100%

1. CLI 层（入口）

bin/next.ts（704 行）：

基于 Commander.js 的命令行
10+ 个子命令：dev、build、start、analyze、info、telemetry、typegen、upgrade 等
预操作钩子：环境验证、NODE_ENV 设置、Node.js 版本检查、React 依赖检查
架构检查（Apple Silicon Rosetta 2 警告）

cli/next-dev.ts（~600 行）：

spawn 子进程隔离 dev server
dev 状态持久化（.next-dev-state.json）
"rage restarts" 检测（90 秒内多次重启）
端口冲突处理、HTTPS 自签证书
集成 tracing 和 CPU profiling

cli/next-build.ts：

编排构建管线（../build/index.ts）
支持 Webpack/Rspack/Turbopack 选择
Debug 模式：--debug-prerender、--experimental-debug-memory-usage

cli/next-start.ts：

启动生产服务器（startServer()）
Inspector 调试支持、keep-alive 超时配置

2. Server 层（核心请求处理，539 文件）

请求处理流程

浏览器请求
  ↓
router-server.ts (940行)       ← HTTP 服务器编排、路由初始化、中间件
  ↓
base-server.ts (3073行)        ← 抽象基类：路由匹配、请求增强、响应格式化
  ├─ handleRequest()           ← 主入口（含 tracing）
  ├─ handleRequestImpl()       ← 核心路由逻辑（1635行）
  ├─ renderToResponseWithComponents() ← 渲染组件树
  ├─ renderHTML()              ← HTML 渲染管线
  └─ renderError()             ← 错误页面渲染
  ↓
┌─────────────────┬──────────────────┐
│  Pages Router   │    App Router    │
│ pages-router/   │   app-render/    │
│   render.ts     │ app-render.tsx   │
│                 │ (8808行，核心)   │
└─────────────────┴──────────────────┘
  ↓
RSC Payload + HTML 流式响应
  ↓
send-response.ts → 浏览器

路由系统

RouteMatcherManager — 管理所有路由匹配
4 种匹配器：AppPage、AppRoute、Pages、PagesAPI
路径规范化器：Locale、RSC、NextData

next-server.ts（2180 行，生产服务器）

加载构建产物 Manifest：BUILD_MANIFEST、PRERENDER_MANIFEST、APP_PATHS_MANIFEST、ROUTES_MANIFEST
ISR 支持、资源优化引用

next-dev-server.ts（开发服务器）

三种 Hot Reloader：
- hot-reloader-webpack.ts（65KB）
- hot-reloader-turbopack.ts（60KB）
- hot-reloader-rspack.ts（8KB）
Fast Refresh 集成、错误覆盖通信

server/lib/ 目录（89 文件）

模块	作用
`router-utils/`	路由构建、路径解码
`incremental-cache/`	ISR、重验证、标签缓存
`cache-handlers/`	文件系统/内存/自定义缓存后端
`start-server.ts`	HTTP/HTTPS 服务器启动
`patch-fetch.ts`	Fetch 拦截（流式、去重）
`cache-control.ts`	Cache-Control 头生成

3. App Render 系统（84 文件，最核心）

app-render.tsx（8808 行）

主导出：renderToHTMLOrFlight — 渲染为 HTML 或 Flight 格式

职责：

React Server Component (RSC) 渲染
流式 HTML 响应生成
Flight 序列化（客户端导航）
错误处理与恢复
Metadata 提取
CSS-in-JS 收集
预取提示生成

子模块分类

核心渲染管线：

模块	作用
`create-component-tree.tsx`	构建 App 组件树
`create-flight-router-state.ts`	导航状态构建
`walk-tree-with-flight-router-state.tsx`	组件树遍历
`stream-ops.ts`	流组合：`chainStreams()`、`renderToWebFlightStream()`
`action-handler.ts`	Server Actions 处理
`dynamic-rendering.ts`	ISR/动态渲染检测
`encryption.ts`	Action 载荷加密
`postponed-state.ts`	PPR 动态延迟
`staged-rendering.ts`	多阶段渲染（静态外壳 → 动态内容）

Async Storage（6 个请求上下文存储）：

work-async-storage — 请求上下文
work-unit-async-storage — 验证状态
action-async-storage — Server Action 上下文
console-async-storage — Console 输出捕获
dynamic-access-async-storage — 动态访问追踪
after-task-async-storage — 后台任务调度

安全：

csrf-protection.ts — CSRF Token 验证
encryption.ts — Action 闭包变量加密

4. Build 系统（265 文件）

build/index.ts（4406 行）

构建阶段：

初始化 — 加载环境/配置/验证项目
路由发现 — 扫描 pages/app 目录
Manifest 构建 — 路由/预渲染/中间件 manifest
编译 — Webpack/Turbopack 打包
优化 — Tree Shaking、代码分割、压缩
完成 — Manifest 写入、Trace 收集

Webpack 插件（26 个）

插件	作用
`flight-manifest-plugin.ts`	SC/CC 引用映射
`pages-manifest-plugin.ts`	Pages 路由映射
`middleware-plugin.ts`	Edge Middleware 处理
`next-trace-entrypoints-plugin.ts`	构建追踪

其他子系统

turbopack-build/ — Turbopack 构建
turbopack-analyze/ — Bundle 分析
babel/ — 自定义 Babel 插件
static-paths/ — 静态预渲染
segment-config/ — 段配置元数据提取

5. Client 运行时（190 文件）

核心文件

文件	作用
`app-index.tsx`	App Router 初始化入口
`app-router.tsx`	App Router 主组件
`layout-router.tsx`	嵌套布局渲染
`navigation.ts`	useRouter/usePathname/useSearchParams
`link.tsx`	Link 组件（预取 + 客户端导航）
`image-component.tsx`	Image 优化组件
`error-boundary.tsx`	客户端错误边界
`form.tsx`	Form 组件

components/ 目录（46 文件）

路由：app-router-instance.ts、links.ts
错误：error-boundary.tsx、catch-error.tsx
表单：form-shared.tsx
工具：promise-queue.ts、offline.ts
内置页面：not found、forbidden、error

6. Shared 工具（159 文件）

shared/lib/router/utils/ — 路由匹配、正则生成、动态路由解析
constants.ts（1073 个导出标识符）— RSC_HEADER、BUILD_MANIFEST 等
shared/lib/router/routes/ — 路由定义和匹配

7. 其他包

包	作用
`create-next-app`	项目脚手架 CLI
`font`	字体优化
`eslint-plugin-next`	ESLint 规则
`next-swc`	SWC 编译器绑定
`next-codemod`	自动化代码升级
`next-env`	环境变量加载

8. Rust Crates（10 个）

Crate	作用
`next-core`	核心逻辑（40 个 src 目录）
`next-api`	API 绑定（27 个 src 目录）
`next-build`	构建系统
`next-custom-transforms`	SWC 自定义转换
`next-error-code-swc-plugin`	错误代码转换
`next-code-frame`	错误代码帧生成
`next-napi-bindings`	Node API 绑定
`next-taskless`	无 turbo-tasks 依赖的工具
`next-build-test`	构建测试二进制
`wasm`	WebAssembly @next/swc

9. Turbopack（55 个 Rust crate）

turbo-tasks/ — 基于图的计算引擎（带缓存）
turbopack-core/ — 打包核心
turbopack-ecmascript/ — JS/TS 解析和打包
turbopack-node/ — Node.js 运行时
turbopack-dev-server/ — HMR 和实时刷新

10. 测试体系

目录	用途	规模
`test/e2e/`	端到端测试（Playwright）	182 个目录
`test/integration/`	功能集成测试	277 个目录
`test/production/`	生产场景测试	80 个目录
`test/development/`	开发模式测试	45 个目录
`test/unit/`	单元测试	62 个目录

第八部分：五阶段学习路线与实战项目

阶段一：入门基础（1-2 周）

目标：能创建和运行一个完整的 Next.js 应用

天	学习内容	文档页面	源码阅读
1	安装、项目结构	Installation, Project Structure	`bin/next.ts`
2	页面、布局、嵌套路由	Layouts and Pages	`app/layout.tsx` 约定
3	导航、Link 组件、预取	Linking and Navigating	`client/link.tsx`
4	CSS、Tailwind、CSS Modules	CSS	无需
5	图片优化、字体优化	Image/Font Optimization	`client/image-component.tsx`
6-7	动态路由、路由组、搜索参数	Layouts and Pages（深入）	`shared/lib/router/utils/`

练习项目：创建个人主页（多页面、导航栏、动态路由、样式、图片）

阶段二：核心概念深入（2-3 周）

目标：掌握 SC/CC 模型、数据流和缓存系统

天	学习内容	文档页面	源码阅读
1-2	Server/Client Components	Server and Client Components	RSC Payload 格式
3-4	数据获取（fetch/ORM/Streaming）	Fetching Data	`server/app-render/` 入口
5-6	Server Actions、表单处理	Mutating Data, Forms	`action-handler.ts`
7-8	缓存系统（use cache/cacheLife）	Caching	`incremental-cache/`
9-10	重验证策略	Revalidating, How Revalidation Works	`cache-handlers/`
11-12	错误处理（error.js/notFound）	Error Handling	`error-boundary.tsx`
13-14	Route Handlers、Metadata/SEO	Route Handlers, Metadata	`route.js` 约定

练习项目：全栈 CRUD 博客（SC 获取数据、SA 表单提交、缓存、错误处理）

阶段三：高级特性（2-3 周）

目标：掌握流式渲染、安全、部署

天	学习内容	文档页面	源码阅读
1-3	Streaming 流式渲染	Streaming, Rendering Philosophy	`stream-ops.ts`, `staged-rendering.ts`
4-5	Proxy（原 Middleware）	Proxy	`proxy.ts` 约定
6-7	认证与安全	Authentication, Data Security	`csrf-protection.ts`, `encryption.ts`
8-9	国际化	Internationalization	`locale-*` 相关模块
10-11	自托管与部署	Self-Hosting, Deploying, Deploying to Platforms	`config.ts`
12-14	测试（Jest/Playwright）	Testing 全部	test/ 目录结构

练习项目：多语言电商 Dashboard（Streaming、认证、i18n、自托管 Docker）

阶段四：源码阅读（3-4 周）

目标：理解框架内部实现

推荐阅读顺序：

bin/next.ts → cli/next-dev.ts → cli/next-build.ts（理解启动）
server/lib/router-server.ts（940 行，全部读）→ base-server.ts（关注 handleRequest）
server/app-render/app-render.tsx（用 grep 定位关键函数，按需读片段）
build/index.ts（理解构建阶段）→ webpack/plugins/
client/app-index.tsx → client/components/app-router.tsx（理解客户端运行时）

开发环境命令：

pnpm install                  # 安装依赖
pnpm --filter=next dev        # 增量构建（1-2 秒/变更）
pnpm --filter=next types      # 类型检查（10 秒）
pnpm --filter=next build      # 完整构建（60 秒）
NEXT_SKIP_ISOLATE=1 pnpm testheadless test/path/to/test.ts  # 快速测试
DEBUG=next:* next dev          # 调试日志

阶段五：实战项目（2-4 周）

项目一：技术博客（初级）

App Router、布局、动态路由
MDX 渲染、Metadata、SEO
静态生成 + ISR、RSS
Tailwind CSS、暗色模式

项目二：全栈任务管理（中级）

SC + CC 组合、Server Actions
数据库（Prisma/Drizzle）、认证（NextAuth）
缓存 + 重验证、乐观更新
错误处理、权限控制

项目三：实时 Dashboard（高级）

Streaming + PPR、并行路由
Route Handlers（WebSocket/SSE）
国际化、多租户
Docker 自托管、性能监控

项目四：参与 Next.js 开源

阅读 contributing.md
从 good first issue 开始
使用 pnpm new-test -- --args true name e2e 创建测试
提交前 pnpm lint + 相关测试
遵循 Conventional Commits

每日学习节奏

1. 阅读文档对应章节（30-40 分钟）
2. 动手编写代码示例（40-60 分钟）
3. 阅读对应源码实现（30-40 分钟）
4. 总结笔记，关联文档与源码（10-20 分钟）

学习原则

先会用再看源码 — 不要一开始就钻进 8808 行的 app-render.tsx
动手优先 — 每个概念都写代码验证
理解 Why — 为什么 Next.js 选择组件级而非路由级的静态/动态边界？
文档-源码对照 — 文档说的 API 在源码哪里实现？
循序渐进 — 不跳过阶段二直接看阶段四

最后更新：2026-05-09 覆盖范围：426 个 MDX 文档文件 + 1601 个 TypeScript 源码文件 + 10 个 Rust crate + 55 个 Turbopack crate 本指南基于 6 个并行 Agent 全面阅读所有文档和源码后编写