nextjs

Next.js App Router - 生产模式

版本：Next.js 16.2.0 React 版本：19.2.0 Node.js：20.9+ 最后验证时间：2025-11-21

目录

1. 何时使用此技能
2. 何时不使用此技能
3. Next.js 16 重大变更
4. 缓存组件与缓存 API
5. 服务端组件
6. 服务端操作
7. 路由处理程序
8. React 19.2 功能
9. 元数据 API
10. 图像与字体优化
11. 最常见的 5 个严重错误
12. 性能模式
13. TypeScript 配置

---

何时使用此技能

在以下情况下使用此技能：

• Next.js 16 App Router 模式（布局、加载、错误边界、路由）
• 服务端组件最佳实践（数据获取、组合、流式传输）
• 服务端操作模式（表单、变更、重新验证、错误处理）
• 使用 "use cache" 指令的缓存组件（Next.js 16 中的新功能）
• 新的缓存 API：revalidateTag()、updateTag()、refresh()（在 Next.js 16 中更新）
• 从 Next.js 15 迁移到 16（异步参数、proxy.ts、并行路由）
• 路由处理程序（API 端点、Webhook、流式响应）
• 代理模式（Next.js 16 中，proxy.ts 取代 middleware.ts）
• 异步路由参数（params、searchParams、cookies()、headers() 现在都是异步的）
• 带有 default.js 的并行路由（Next.js 16 中的重大变更）
• React 19.2 功能（视图过渡、useEffectEvent()、React Compiler）
• 元数据 API（SEO、Open Graph、Twitter Cards、站点地图）
• 图像优化（Next.js 16 中更新了默认设置的 next/image）
• 性能优化（延迟加载、代码拆分、PPR、ISR）

何时不使用此技能

以下情况请勿使用此技能：

• 部署到 Cloudflare Workers → 使用 cloudflare-nextjs 技能（OpenNext 适配器：@opennextjs/cloudflare、getCloudflareContext、缓存层级、Workers 专属错误）。注意：cloudflare-nextjs 涵盖了 Cloudflare 的 proxy.ts 例外情况（在那里保留 middleware.ts）。
• Pages Router 模式 → 此技能仅涵盖 App Router（Pages Router 已过时）
• 身份验证库 → 使用 clerk-auth、auth-js 或其他身份验证专用技能
• 数据库集成 → 使用 cloudflare-d1、drizzle-orm-d1 或数据库专用技能
• UI 组件库 → 使用 tailwind-v4-shadcn 技能处理 Tailwind + shadcn/ui
• 状态管理 → 使用 zustand-state-management、tanstack-query 技能
• 表单库 → 使用 react-hook-form-zod 技能

---

Next.js 16 重大变更

重要：Next.js 16 有多项重大变更。详细迁移步骤请参阅 references/next-16-migration-guide.md。

重大变更	之前	之后
异步参数	params.slug	const { slug } = await params
异步请求头	cookies() 同步调用	await cookies()
中间件	middleware.ts	proxy.ts（重命名）
并行路由	default.js 可选	必须使用 default.js
缓存	自动缓存 fetch	通过 "use cache" 显式启用
revalidateTag()	1 个参数	2 个参数（标签 + cacheLife）
Node.js	18.x+	必须为 20.9+
React	18.x	必须为 19.2+

异步参数快速修复：

// ✅ Next.js 16 pattern
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  return <div>{id}</div>
}

Codemod：bunx @next/codemod@canary upgrade latest

参阅：references/next-16-migration-guide.md，其中包含完整迁移指南和示例。

---

缓存组件与缓存 API

"use cache" 指令（Next.js 16 中的新功能）

'use cache'

export async function BlogPosts() {
  const posts = await db.posts.findMany()
  return posts.map(post => <article key={post.id}>{post.title}</article>)
}

缓存 API 概览

API	用途	示例
"use cache"	选择启用组件／函数缓存	在顶部添加 'use cache'
revalidateTag()	按标签使缓存失效	revalidateTag('posts', 'max')
updateTag()	更新缓存而不重新验证	updateTag('posts', newData)
refresh()	刷新当前页面	refresh()
revalidatePath()	按路径使缓存失效	revalidatePath('/posts')

PPR（部分预渲染）

// next.config.ts
const config = { experimental: { ppr: true } }

// page.tsx
export const experimental_ppr = true

export default function Page() {
  return (
    <>
      <StaticHeader />
      <Suspense fallback={<Skeleton />}>
        <DynamicContent />
      </Suspense>
    </>
  )
}

参见：references/caching-apis.md，了解完整的缓存 API 参考，包括 ISR、基于标签的重新验证和高级模式。

---

服务端组件

服务端组件是 App Router 中的默认组件。它们在服务端运行，可以获取数据、访问数据库，并将逻辑保留在服务端。

// app/posts/page.tsx (Server Component by default)
export default async function PostsPage() {
  const posts = await db.posts.findMany()
  return <div>{posts.map(p => <article key={p.id}>{p.title}</article>)}</div>
}

使用 Suspense 实现流式传输

import { Suspense } from 'react'

export default function Page() {
  return (
    <div>
      <Header />
      <Suspense fallback={<Skeleton />}>
        <Posts />
      </Suspense>
    </div>
  )
}

服务端组件与客户端组件

服务端组件	客户端组件
数据获取、数据库访问	交互功能（onClick）
敏感逻辑	React 钩子（useState）
大型依赖项	浏览器 API
静态内容	实时更新

客户端组件（需要 'use client'）：

'use client'
import { useState } from 'react'
export function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

---

服务端操作

服务端操作是在服务端运行的异步函数，可从客户端组件或服务端组件调用。

基本服务端操作

// app/actions.ts
'use server'

import { revalidatePath } from 'next/cache'

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string
  await db.posts.create({ data: { title } })
  revalidatePath('/posts')
}

表单处理

// Server Component Form (simplest)
import { createPost } from './actions'

export default function NewPostPage() {
  return (
    <form action={createPost}>
      <input name="title" required />
      <button type="submit">Create</button>
    </form>
  )
}

可用模式

模式	使用场景	参考
带加载状态的客户端表单	useFormState + useFormStatus	templates/server-action-form.tsx
错误处理	返回 { error } 或 { success }	references/server-actions-patterns.md
乐观更新	useOptimistic 钩子	references/server-actions-patterns.md
文件上传	FormData + blob 存储	references/server-actions-patterns.md
操作后重定向	redirect() 函数	references/server-actions-patterns.md

参见：references/server-actions-patterns.md，了解错误处理、乐观更新、文件上传和高级模式。

---

路由处理器

路由处理器是 App Router 中与 API Routes 对应的功能。

// app/api/posts/route.ts
export async function GET(request: Request) {
  const posts = await db.posts.findMany()
  return Response.json({ posts })
}

export async function POST(request: Request) {
  const body = await request.json()
  const post = await db.posts.create({ data: body })
  return Response.json({ post }, { status: 201 })
}

动态路由（使用异步 params）：

// app/api/posts/[id]/route.ts
export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params // Await in Next.js 16
  const post = await db.posts.findUnique({ where: { id } })
  return post ? Response.json({ post }) : Response.json({ error: 'Not found' }, { status: 404 })
}

参见：templates/route-handler-api.ts，了解搜索参数、webhook 和流式传输模式。

---

React 19.2 功能

功能	用法
React Compiler	experimental: { reactCompiler: true } - 自动记忆化
视图过渡	useTransition() + router.push()
useEffectEvent	无需 deps 的稳定事件处理器

---

元数据 API

// Static metadata
export const metadata: Metadata = {
  title: 'My Blog',
  description: 'A blog about Next.js',
  openGraph: { title: 'My Blog', images: ['/og-image.jpg'] },
}

// Dynamic metadata (await params in Next.js 16)
export async function generateMetadata({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  const post = await db.posts.findUnique({ where: { id } })
  return { title: post.title, description: post.excerpt }
}

---

图像与字体优化

// next/image
import Image from 'next/image'
<Image src="/profile.jpg" alt="Profile" width={500} height={500} priority />

// next/font
import { Inter } from 'next/font/google'
const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
<html className={inter.variable}>

远程图像：在 next.config.ts 中配置 images.remotePatterns。

---

最重要的 5 个错误

错误 1：params 是一个 Promise

错误：Type 'Promise<{ id: string }>' is not assignable to type '{ id: string }'

解决方案：在 Next.js 16 中等待 params：

export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
}

---

错误 2：middleware.ts 已弃用

警告：middleware.ts is deprecated. Use proxy.ts instead.

解决方案：重命名文件和函数：

// Rename: middleware.ts → proxy.ts
// Rename function: middleware → proxy
export function proxy(request: NextRequest) {
  // Same logic
}

---

错误 3：并行路由缺少 default.js

错误：Parallel route @modal was matched but no default.js was found

解决方案：添加 default.tsx：

// app/@modal/default.tsx
export default function ModalDefault() {
  return null
}

---

错误 4：无法在服务端组件中使用 React 钩子

错误：You're importing a component that needs useState. It only works in a Client Component

解决方案：添加 'use client'：

'use client'

import { useState } from 'react'

export function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

---

错误 5：fetch() 未缓存

原因：Next.js 16 使用选择启用的缓存机制，需添加 "use cache"。

解决方案：添加 "use cache" 指令：

'use cache'

export async function getPosts() {
  const response = await fetch('/api/posts')
  return response.json()
}

---

查看全部 18 个错误：references/error-catalog.md

---

性能模式

模式	用途
延迟加载	const HeavyComp = dynamic(() => import('./Heavy'), { ssr: false })
代码拆分	按路由自动拆分——每个 page.tsx 都有自己的包
Turbopack	Next.js 16 中的默认选项，可使用 --webpack 标志退出
PPR	experimental: { ppr: true } + <Suspense> 边界

---

TypeScript 配置

{
  "compilerOptions": {
    "strict": true,
    "baseUrl": ".",
    "paths": { "@/*": ["./*"] }
  }
}

---

何时加载参考资料

参考资料	加载时机……
next-16-migration-guide.md	从 Next.js 15 迁移、异步参数错误、proxy.ts 设置
server-actions-patterns.md	错误处理、乐观更新、文件上传、高级表单
caching-apis.md	ISR、基于标签的重新验证、updateTag()、refresh()、PPR 详情
error-catalog.md	调试任何 Next.js 错误、全面的错误解决方案
top-errors.md	快速修复最常见的 5 个 Next.js 错误

---

捆绑资源

类型	文件
参考资料	error-catalog.md、top-errors.md、next-16-migration-guide.md、server-actions-patterns.md、caching-apis.md
模板	async-params-page.tsx、server-action-form.tsx、route-handler-api.ts、cache-component-use-cache.tsx、parallel-routes-with-default.tsx、proxy-migration.ts

---

相关技能

技能	用途
cloudflare-nextjs	通过 OpenNext 适配器（@opennextjs/cloudflare）部署到 Cloudflare Workers
tailwind-v4-shadcn	样式
clerk-auth	身份验证
drizzle-orm-d1	数据库
react-hook-form-zod	表单
zustand-state-management	客户端状态

官方文档：https://nextjs.org/docs | App Router：https://nextjs.org/docs/app

---

版本：Next.js 16.2.0 | React 19.2.0 | Node.js 20.9+ | TypeScript 5.9+ 生产环境测试：电子商务、SaaS、内容网站 | Token 节省：65-70%