名称：nextjs 描述：Next.js 16 包含 App Router、Server Components、Server Actions、Cache Components。适用于 React 19.2 应用、SSR，或处理异步参数、proxy.ts 迁移、use cache 错误。

关键词：Next.js 16, Next.js App Router, Next.js Pages Router, Server Components, React Server Components, Server Actions, Cache Components, use cache, Next.js 16 破坏性变化, async params nextjs, proxy.ts 迁移, React 19.2, Next.js 元数据, Next.js SEO, generateMetadata, 静态生成, 动态渲染, 流式 SSR, Suspense, 并行路由, 拦截路由, 路由组, Next.js 中间件, Next.js API 路由, Route Handlers, revalidatePath, revalidateTag, next/navigation, useSearchParams, turbopack, next.config 许可证：MIT 元数据：版本：1.0.0 最后验证：2025-11-21 nextjs_version：16.0.3 react_version：19.2.0 node_version：20.9+ 作者：Claude Skills Maintainers 仓库：https://github.com/secondsky/claude-skills production_tested：true token_savings：65-70% errors_prevented：18+ 允许工具：[“Read”, “Write”, “Edit”, “Bash”, “Glob”, “Grep”]

Next.js App Router - 生产模式

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

何时使用此技能

使用此技能当您需要：

Next.js 16 App Router 模式（布局、加载、错误边界、路由）
Server Components 最佳实践（数据获取、组合、流式）
Server Actions 模式（表单、突变、重新验证、错误处理）
Cache Components 与 "use cache" 指令（Next.js 16 新增）
新缓存 API：revalidateTag(), updateTag(), refresh()（Next.js 16 更新）
从 Next.js 15 迁移到 16（异步参数、proxy.ts、并行路由）
Route Handlers（API 端点、webhooks、流式响应）
代理模式（proxy.ts 在 Next.js 16 中替换 middleware.ts）
异步路由参数（params, searchParams, cookies(), headers() 现在异步）
并行路由与 default.js（Next.js 16 的破坏性变化）
React 19.2 特性（View Transitions, useEffectEvent(), React Compiler）
Metadata API（SEO、Open Graph、Twitter Cards、站点地图）
图片优化（next/image 在 Next.js 16 中更新默认设置）
性能优化（懒加载、代码分割、PPR、ISR）

何时不使用此技能

不要使用此技能于：

Cloudflare Workers 部署 → 使用 cloudflare-nextjs 技能代替
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 模式
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  return <div>{id}</div>
}

代码修改：bunx @next/codemod@canary upgrade latest

参考：references/next-16-migration-guide.md 获取完整迁移指南和示例。

Cache Components & Caching APIs

`"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>)
}

Caching APIs 摘要

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、基于标签的重新验证和高级模式。

Server Components

Server Components 在 App Router 中是默认的。它们在服务器上运行，可以获取数据、访问数据库并保持逻辑在服务器端。

// app/posts/page.tsx（默认 Server Component）
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>
  )
}

Server vs Client Components

Server Components	Client Components
数据获取、数据库访问	交互性（onClick）
敏感逻辑	React hooks（useState）
大型依赖	浏览器 API
静态内容	实时更新

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>
}

Server Actions

Server Actions 是异步函数，在服务器上运行，可从 Client 或 Server Components 调用。

基本 Server Action

// 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（最简单）
import { createPost } from './actions'

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

可用模式

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

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

Route Handlers

Route Handlers 是 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 })
}

动态路由（使用异步参数）：

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

参考：templates/route-handler-api.ts 获取搜索参数、webhooks 和流式模式。

React 19.2 特性

特性	用法
React Compiler	`experimental: { reactCompiler: true }` - 自动记忆化
View Transitions	`useTransition()` + `router.push()`
useEffectEvent	稳定的事件处理器，无需依赖项

Metadata API

// 静态元数据
export const metadata: Metadata = {
  title: '我的博客',
  description: '关于 Next.js 的博客',
  openGraph: { title: '我的博客', images: ['/og-image.jpg'] },
}

// 动态元数据（在 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 }
}

Image & Font Optimization

// next/image
import Image from 'next/image'
<Image src="/profile.jpg" alt="个人资料" 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。

Top 5 Critical Errors

错误 1：`params` 是一个 Promise

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

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

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.

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

// 重命名：middleware.ts → proxy.ts
// 重命名函数：middleware → proxy
export function proxy(request: NextRequest) {
  // 相同逻辑
}

错误 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：不能在 Server Component 中使用 React hooks

错误：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`

Next.jsAppRouter-生产模式 nextjs