nextjs-16

涵盖 Next.js 16 的核心框架机制（当前稳定版：16.3）：Turbopack（默认打包器；可通过 `--webpack` 退出标记继续使用 Webpack）、App Router（嵌套布局、并行路由/拦截路由，以及 `page.tsx`/`layout.tsx`/`loading.tsx`/`error.tsx`/`not-found.tsx` 等文件约定）、缓存组件（`use cache`、`cacheTag()`、`cacheLife()`、`revalidateTag()`）、`proxy.ts`（完整的 Node.js 运行时，取代 Edge 中间件）以及 React 19 集成（视图过渡、新 Hook）。

说明 v15→v16 的关键破坏性变更：proxy.ts 取代 middleware.ts、Turbopack 成为 next dev/next build 的默认选项、cacheComponents 取代已移除的 experimental.ppr 标记、必须使用 React 19，以及 params/searchParams 改为异步。本技能仅涵盖核心框架 API；如需组建完整的生产技术栈（同时使用 Prisma、Better Auth、shadcn/ui、Zustand），请改用 nextjs-stack；如需不使用 next.config.* 的纯 React SPA，请改用 react-expert 技能。

Next.js 16 专家

生产就绪的 React 框架，支持服务器组件、流式传输和 Turbopack。

Agent 工作流（必须遵循）

在进行任何实现之前，启动 3 个并行 Agent，每个 Agent 调用都必须指定一个 name：

1. fuse-ai-pilot:explore-codebase - 分析现有路由、组件和模式
2. fuse-ai-pilot:research-expert - 通过 Context7/Exa 核实最新的 Next.js 16 文档
3. mcp__context7__query-docs - 检查 v15→v16 的破坏性变更

实现完成后，运行 fuse-ai-pilot:sniper 进行验证。

---

概述

适用场景

• 使用服务器优先架构构建新的 React 应用
• 需要服务器组件以实现最佳性能和 SEO
• 实现流式传输和渐进式渲染
• 从 Next.js 14/15 迁移到版本 16
• 使用 proxy.ts 保护路由（取代中间件）
• 利用 Turbopack 加快开发构建速度

为什么选择 Next.js 16

特性	优势
默认使用 Turbopack	构建速度提升 2–5 倍，HMR 速度提升 10 倍；仅通过 --webpack 退出标记使用 Webpack
缓存组件	使用 use cache 指令进行显式缓存
proxy.ts	完整的 Node.js 运行时，取代 Edge 中间件
React Compiler	自动记忆化，无需手动使用 useMemo/useCallback
React 19	视图过渡、useEffectEvent、Activity 组件
App Router	嵌套布局、并行路由、拦截路由

---

v15 的破坏性变更

关键迁移事项

1. proxy.ts 取代 middleware.ts - 使用完整的 Node.js 运行时，而非 Edge
2. 默认使用 Turbopack - next dev/next build 使用 Turbopack；如果存在自定义 webpack 配置，除非迁移配置或通过 --webpack 退出，否则构建会失败
3. cacheComponents + use cache - 取代已移除的 experimental.ppr / experimental_ppr；在 cacheComponents 下，PPR 默认启用
4. 必须使用 React 19 - 支持新的 Hook 和视图过渡 API
5. 异步 params/searchParams - 必须等待动态路由参数

16.1 – 16.3 新增内容（参见 upgrade.md）

• 16.1 - Turbopack 文件系统缓存默认用于 next dev；next dev --inspect
• 16.2 - <Link> 的 transitionTypes 属性、next start --inspect、Adapters API 稳定
• 16.3 - catchError + retry() 错误恢复（稳定版）、next/root-params、import.meta.glob、Turbopack 构建缓存默认启用、可选启用即时导航（在 cacheComponents 下使用 partialPrefetching）

---

SOLID 架构

基于模块的结构

页面是从功能模块导入内容的精简入口：

• app/page.tsx → 从 modules/public/home/ 导入
• app/dashboard/page.tsx → 从 modules/auth/dashboard/ 导入
• modules/cores/ → 共享服务、实用工具、配置

文件约定

• page.tsx - 路由 UI 组件
• layout.tsx - 共享 UI 包装器
• loading.tsx - Suspense 加载状态
• error.tsx - 错误边界
• not-found.tsx - 404 处理

---

核心概念

服务端组件（默认）

所有组件默认都是服务端组件。仅在需要交互性、钩子或浏览器 API 时使用 'use client' 指令。

缓存策略

• use cache —— 标记要缓存的异步函数
• cacheTag() —— 为缓存数据添加标签，以便有针对性地重新验证
• cacheLife() —— 控制缓存时长（过期前可用、重新验证、过期）
• revalidateTag() —— 按需使缓存数据失效

数据获取

服务端组件直接获取数据。使用带有原生缓存的 fetch() 或数据库查询。无需使用 getServerSideProps 或 getStaticProps。

---

参考指南

需求	参考资料
初始设置	installation.md, project-structure.md
从 v15 迁移到 v16	upgrade.md, middleware-migration.md
路由	app-router.md, routing-advanced.md
缓存	caching.md, cache-components.md
服务端组件	server-components.md, directives.md
React 19 功能	react-19.md, react-compiler.md
路由保护	proxy.md, security.md
SEO/元数据	metadata.md, metadata-files.md
表单/操作	forms.md, data-fetching.md
部署	deployment.md, environment.md

---

最佳实践

1. 优先使用服务端组件 —— 仅在必要时添加 'use client'
2. 就近获取数据 —— 在使用数据的位置获取数据
3. 使用 Suspense 实现流式传输 —— 用 Suspense 包裹耗时组件
4. 优先使用 proxy.ts 而非 middleware —— 为身份验证提供完整的 Node.js 运行时
5. 显式缓存 —— 对开销较大的操作使用 use cache
6. 并行路由 —— 同时加载彼此独立的 UI 区域

---

性能

构建优化

• Turbopack —— 增量编译，HMR 即时生效
• React Compiler —— 自动记忆化
• Tree shaking —— 移除未使用的代码
• 代码拆分 —— 自动按路由拆分

运行时优化

• 流式传输 —— 渐进式 HTML 渲染
• 部分水合 —— 仅水合交互式组件
• 图像优化 —— 自动转换为 WebP/AVIF
• 字体优化 —— 使用 next/font 实现零布局偏移