nextjs-16

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Next.js 16 Expert

Next.js 16 专家指南

Production-ready React framework with Server Components, streaming, and Turbopack.

一款支持Server Components、流式渲染和Turbopack的生产级React框架。

Agent Workflow (MANDATORY)

Agent工作流（强制要求）

Before ANY implementation, use

TeamCreate

to spawn 3 agents:

fuse-ai-pilot:explore-codebase - Analyze existing routes, components, and patterns
fuse-ai-pilot:research-expert - Verify latest Next.js 16 docs via Context7/Exa
mcp__context7__query-docs - Check breaking changes v15→v16

After implementation, run fuse-ai-pilot:sniper for validation.

在进行任何实现之前，使用

TeamCreate

生成3个Agent：

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

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

Overview

概述

When to Use

适用场景

Building new React applications with server-first architecture
Need Server Components for optimal performance and SEO
Implementing streaming and progressive rendering
Migrating from Next.js 14/15 to version 16
Using proxy.ts for route protection (replaces middleware)
Leveraging Turbopack for faster development builds

采用服务端优先架构构建新的React应用
需要Server Components以实现最优性能和SEO效果
实现流式渲染和渐进式渲染
从Next.js 14/15版本迁移到16版本
使用proxy.ts进行路由保护（替代middleware）
借助Turbopack实现更快的开发构建

Why Next.js 16

选择Next.js 16的理由

Feature	Benefit
Turbopack default	2-5x faster builds, 10x faster HMR, Webpack deprecated
Cache Components	Explicit caching with `use cache` directive
proxy.ts	Full Node.js runtime, replaces Edge middleware
React Compiler	Automatic memoization, no manual useMemo/useCallback
React 19	View Transitions, useEffectEvent, Activity component
App Router	Nested layouts, parallel routes, intercepting routes

特性	优势
默认使用Turbopack	构建速度提升2-5倍，HMR速度提升10倍，Webpack已被弃用
缓存组件	通过 `use cache` 指令实现显式缓存
proxy.ts	完整Node.js运行时，替代Edge中间件
React编译器	自动记忆化，无需手动使用useMemo/useCallback
React 19	视图过渡、useEffectEvent、Activity组件
App Router	嵌套布局、并行路由、拦截路由

Breaking Changes from v15

v15到v16的破坏性变更

Critical Migration Points

关键迁移要点

proxy.ts replaces middleware.ts - Full Node.js runtime, not Edge
Turbopack ONLY - Webpack completely deprecated and removed
use cache
directive - Replaces Partial Prerendering (PPR)
React 19 required - New hooks and View Transitions API
Async params/searchParams - Must await dynamic route params

proxy.ts替代middleware.ts - 采用完整Node.js运行时，而非Edge环境
仅支持Turbopack - Webpack已被完全弃用并移除
use cache
指令 - 替代部分预渲染（PPR）
必须使用React 19 - 新增钩子和视图过渡API
异步params/searchParams - 必须等待动态路由参数

SOLID Architecture

SOLID架构

Module-Based Structure

基于模块的结构

Pages are thin entry points importing from feature modules:

```
app/page.tsx
```
→ imports from
```
modules/public/home/
```

app/dashboard/page.tsx

→ imports from

modules/auth/dashboard/

```
modules/cores/
```
→ Shared services, utilities, configurations

页面作为轻量入口，导入功能模块中的内容：

```
app/page.tsx
```
→ 导入自
```
modules/public/home/
```

app/dashboard/page.tsx

→ 导入自

modules/auth/dashboard/

```
modules/cores/
```
→ 共享服务、工具函数、配置项

File Conventions

文件约定

page.tsx - Route UI component
layout.tsx - Shared UI wrapper
loading.tsx - Suspense loading state
error.tsx - Error boundary
not-found.tsx - 404 handling

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

Core Concepts

核心概念

Server Components (Default)

服务端组件（默认）

All components are Server Components by default. Use

'use client'

directive only when needed for interactivity, hooks, or browser APIs.

所有组件默认都是服务端组件。仅在需要交互性、钩子或浏览器API时，才添加

'use client'

指令。

Caching Strategy

缓存策略

use cache
- Mark async functions for caching
cacheTag()
- Tag cached data for targeted revalidation
cacheLife()
- Control cache duration (stale, revalidate, expire)
revalidateTag()
- Invalidate cached data on-demand

use cache
- 标记异步函数以启用缓存
cacheTag()
- 为缓存数据添加标签，用于针对性重新验证
cacheLife()
- 控制缓存时长（过期、重新验证、失效）
revalidateTag()
- 按需使缓存数据失效

Data Fetching

数据获取

Server Components fetch data directly. Use

fetch()

with native caching or database queries. No need for

getServerSideProps

getStaticProps

服务端组件直接获取数据。使用原生缓存的

fetch()

或数据库查询。无需使用

getServerSideProps

或

getStaticProps

。

Reference Guide

参考指南

Need	Reference
Initial setup	installation.md, project-structure.md
Migration v15→v16	upgrade.md, middleware-migration.md
Routing	app-router.md, routing-advanced.md
Caching	caching.md, cache-components.md
Server Components	server-components.md, directives.md
React 19 features	react-19.md, react-compiler.md
Route protection	proxy.md, security.md
SEO/Metadata	metadata.md, metadata-files.md
Forms/Actions	forms.md, data-fetching.md
Deployment	deployment.md, environment.md

需求	参考文档
初始设置	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

Best Practices

最佳实践

Server Components first - Only add
```
'use client'
```
when necessary
Colocate data fetching - Fetch data where it's used
Streaming with Suspense - Wrap slow components in Suspense
proxy.ts over middleware - Full Node.js runtime for auth
Cache explicitly - Use
```
use cache
```
for expensive operations
Parallel routes - Load independent UI sections simultaneously

优先使用服务端组件 - 仅在必要时添加
```
'use client'
```
数据获取与组件同置 - 在使用数据的位置获取数据
结合Suspense实现流式渲染 - 将慢加载组件包裹在Suspense中
使用proxy.ts替代middleware - 利用完整Node.js运行时处理认证
显式配置缓存 - 对耗时操作使用
```
use cache
```
并行路由 - 同时加载独立的UI区域