next-v16

技能：next-v16

Next.js 16 App Router（2025 年 10 月正式发布）。优先使用 node_modules/next/dist/docs/ 中与版本匹配的文档，而不是训练数据。Codemod：npx @next/codemod@canary upgrade latest、middleware-to-proxy、next-async-request-api。

范围

• 适用范围：Next.js 16 App Router — Turbopack、Cache Components 与旧缓存模型、proxy.ts、异步请求 API、Server Components、Server Actions、流式传输、元数据、客户端岛屿
• 不涵盖：Pages Router、通用 React 19（参见 vercel-react）、非 Next 服务端渲染

假设

• Next.js 16.x、React 19.2 App Router、Node.js 20.9+、TypeScript 5.1+
• 存在两种缓存模型。选择 API 前，先检查 next.config 中是否设置了 cacheComponents
• 两种模型中的 fetch 默认都不会缓存。请显式启用

原则

• 生成 Next API 前，先阅读此安装版本的 node_modules/next/dist/docs/
• 缓存需显式启用。对每个服务端 fetch 声明缓存意图
• 网络边界是 proxy.ts（Node.js）。用于身份验证、重写、重定向和修改请求头
• 请求 API 是异步的：await cookies()、await headers()、await draftMode()、await params、await searchParams
• Turbopack 是默认打包器。--webpack 是退出选项，不是 Next.js 16 的惯用做法
• 优先使用 Server Components。将 'use client' 放在交互式叶节点上
• 用户要求审查或现代化 Next 代码时，请遵循 references/_review-algorithm.md

约束

必须

• 对 params、searchParams、cookies()、headers()、draftMode() 使用 await
• 使用带有 cacheLife 配置的 revalidateTag(tag, profile)（'max' | 'hours' | 'days' | 内联 { expire }）。单参数形式已弃用
• 在 Server Actions 中，当用户必须立即看到写入结果时（读写一致性），使用 updateTag(tag)。使用 revalidateTag(tag, 'max') 实现陈旧数据后台重新验证
• 从 proxy.ts 导出 proxy（命名导出或默认导出）。运行时为 nodejs，且无法设置为 Edge
• 添加 'use cache'、cacheLife 或 cacheTag 前，确认已启用 cacheComponents: true

应当

• 仅在明确迁移时启用 Cache Components：设置 cacheComponents: true，然后将分段配置 dynamic / revalidate / fetchCache 替换为 'use cache' + cacheLife。指南：迁移到 Cache Components
• 如果应用未采用 experimental.dynamicIO / experimental.useCache / experimental.ppr，请移除这些标志。不要将 cacheComponents: true 当作重命名来设置——未缓存且位于 Suspense 外的数据可能导致构建失败
• 未启用 Cache Components 时，使用 cache: 'force-cache'、next: { revalidate, tags } 或 unstable_cache 进行缓存。指南：不使用 Cache Components 进行缓存
• 在 proxy.ts 中保留 config.matcher，并排除 /_next/static、/_next/image 和公共资源
• 使用 next/image 的 remotePatterns（不要使用已弃用的 images.domains）。使用 next/image，不要使用 next/legacy/image
• 从 app/sitemap.ts 和 app/robots.ts 生成站点地图和 robots 文件
• 从 next/cache 导入 cacheLife / cacheTag（稳定版）。不要使用 unstable_cacheLife / unstable_cacheTag
• 将 skipMiddlewareUrlNormalize 重命名为 skipProxyUrlNormalize

避免

• 在未设置 cacheComponents: true 的应用中生成 'use cache'（该指令是 Cache Components 功能）
• 因为存在 experimental.dynamicIO / experimental.useCache / experimental.ppr 就启用 cacheComponents: true。启用此标志属于编程模型迁移
• 为新代码使用 middleware.ts。仅在仍需要 Edge 运行时的情况下保留；它已弃用
• 同步使用 params / cookies() / headers()（已移除，不会发出警告）
• 使用 next lint（已移除）。使用 ESLint 或 Biome 运行 lint
• 使用 experimental.ppr、experimental.dynamicIO、experimental.useCache、export const experimental_ppr（已移除）
• 使用 experimental.turbopack（已移至顶层 turbopack）
• 使用 experimental.turbo.persistentCaching——这不是 Next 16 API。文件系统缓存配置为 experimental.turbopackFileSystemCacheForDev / experimental.turbopackFileSystemCacheForBuild（默认启用）
• 将 next dev --turbopack / next build --turbopack 视为 Next 16 的惯用写法。Turbopack 已是默认选项；--webpack 用于选择退出
• 使用默认的 next build 时，在配置中自定义 webpack（会失败）。迁移到 Turbopack 或传入 --webpack
• 将 revalidateTag 中的 'max' 视为“读己之写”。这是 SWR；在 Server Actions 中使用 updateTag
• 声称 Server Actions 必须取代所有 Route Handler。对于 cookies、webhook、OAuth 回调以及代理外部 API，Route Handler 仍是正确选择

交互

• React 19 并发 UI：vercel-react
• 水合后的客户端数据：tanstack-query-v5
• 保留在 Next 服务端的表单：workflow/form

两种缓存模型（不要混用）

配置	应生成的内容
未设置 cacheComponents / 设为 false	旧模型。除非设置 cache: 'force-cache' 或 next.revalidate，否则 fetch 不缓存。分段配置 dynamic、revalidate、fetchCache 仍可用。非 fetch 场景使用 unstable_cache。不要生成 'use cache'
cacheComponents: true	Cache Components。默认动态。使用 'use cache' + cacheLife / cacheTag 进行缓存。分段配置 dynamic / revalidate / fetchCache 会导致错误。PPR 是默认行为。'use cache' 作用域内的 fetch 会被缓存

'use cache' 需要设置 cacheComponents: true（use cache）。启用此标志属于迁移，并非 Next 16 的自动默认设置（cacheComponents）。

失效（两种模型均适用，Next 16 签名）：

• revalidateTag(tag, 'max') — stale-while-revalidate；可用于 Server Actions 和 Route Handlers
• updateTag(tag) — 在同一请求中使缓存过期并读取新数据；仅限 Server Actions
• refresh() — 仅刷新未缓存的数据；仅限 Server Actions
• revalidatePath — 不变

Next.js 16 惯用写法（不要生成 Next 15 写法）

• proxy.ts + export function proxy（Node）——除非需要 Edge，否则不要使用 middleware.ts
• Turbopack 为默认选项——直接运行 next dev / next build，不带 --turbopack。选择退出：--webpack
• await params / await searchParams / await cookies()
• revalidateTag(tag, profile)——不要使用 revalidateTag(tag)
• reactCompiler: true 已稳定，但需选择启用（默认不启用）
• 在 Next 配置根级别使用 turbopack: { ... }——不要使用 experimental.turbopack
• 并行路由插槽需要 default.js（缺少时构建会失败）

如何审查或重构

当用户要求审查、重构、现代化改造或审计 Next 代码时，请遵循 references/_review-algorithm.md。不要自行发挥。

1. 选择模式 A（≤约 20 个文件）或模式 B（整个目录树）
2. 在第 2 类之前检测 next.config 中的缓存模型
3. 按类别进行全面检查，并声明检查范围、逐类别显示进度行，以及提供覆盖范围表
4. 最后处理第 9 类（去重 / 合并 / 删除 / 降级 'use client'）

规则类别

1. 构建与打包 — 严重 — barrels、optimizePackageImports、serverExternalPackages、Turbopack、next/dynamic
2. 缓存 — 严重 — fetch 意图、段配置 或 'use cache'（取决于模型）、revalidateTag+profile、revalidatePath、React cache()
3. 服务端组件 — 高 — 并行 fetch、Suspense、就近放置、预加载、不在客户端初始获取数据
4. 路由 — 高 — 并行/拦截路由、预取、proxy.ts、notFound()
5. 服务端操作 — 中高 — 表单、useFormStatus、操作结果、乐观 UI、重新验证。如果变更已发送到外部 API，则跳过
6. 流式传输 — 中 — Suspense、包含 await 操作的路由上的 loading.tsx、error.tsx、匹配的骨架屏
7. 元数据 — 中 — generateMetadata、sitemap.ts、robots.ts、opengraph-image.tsx
8. 客户端岛 — 低至中 — 'use client' 叶节点、children 插槽、水合、next/script
9. 代码卫生 — 跨领域 — 去重 fetcher、整合路由、死代码、边界审查、命名漂移

完整规则列表：references/compiled.md。规则文件：references/。

参考资料

• Next.js 16 博客
• 升级到 16
• 缓存（Cache Components）
• 不使用 Cache Components 的缓存
• 迁移到 Cache Components
• use cache
• proxy.ts
• middleware → proxy