next-best-practices

Next.js 审查与实现

更改框架行为前，请先查看已安装的 next 版本，以及相关的 node_modules/next/dist/docs/ 页面。这些文档和项目配置优先级更高；如果本地没有文档，请使用匹配的在线版本或源码标签。Next.js 在 vercel/next.js 的 skills/ 中发布工作流技能。

文档随 16.2 版一同打包；在 monorepo 中，请查看应用自身的 next 包。 这些文件中的 nextjs.org 链接在本地都有对应文档，文档按编号文件夹存放，因此请按文件名搜索（find node_modules/next/dist/docs -name proxy.md）。 01-app/02-guides/upgrading/version-16.md 列出了破坏性变更。 针对每个错误的页面（/docs/messages/*）仅在线提供；dev/build 输出中包含该错误的修复选项。 确切的导出内容也列在 node_modules/next/{server,navigation,headers,cache}.d.ts 中。

开始其他工作前，请将已安装版本与 Next.js 安全公告进行比对，并在版本受影响时告知用户。截至 2026-10-22， 16.0.0–16.4.0（在 16.4.1 中修复）和 15.x 中不高于 15.5.27 的版本（在 15.5.28 中修复）存在严重 RCE 漏洞：返回类型化数组的 use cache 函数 （GHSA-673q-mjm6-r5xr，仅影响 16.x，暂无临时解决方案）以及 glibc Linux 上自托管的 SVG 图像优化（GHSA-2464-fhr4-w9xw；临时修复方案：sharp 0.35.5+）。这些版本还存在 Server Actions DoS 漏洞（GHSA-p3m5-59mp-jv5r）。从 16.4 起，experimental.agentUpgrade（默认值为 'security'）会在 next dev/next build 期间提醒；16.3.x 及更早版本不会提醒。

旧示例中未体现的 Next.js 16 变更

• 已移除同步请求访问：cookies()、headers()、draftMode()、 params（包括图像元数据路由）、searchParams 和站点地图 id 都是 Promise。next typegen 会生成全局类型 PageProps<'/route'>、 LayoutProps 和 RouteContext。
• middleware.ts 已弃用：导出 proxy（或 default）的 proxy.ts 仅在 Node.js 上运行，且不接受 runtime 选项；需要 Edge 的代码仍保留在 middleware.ts 中。Codemod：npx @next/codemod@latest middleware-to-proxy .。
• Turbopack 是 dev 和 build 的默认工具；自定义 webpack 配置会导致构建失败，除非使用 --webpack 保留它，或显式指定 --turbopack 忽略它。已移除 next lint，且 next build 不再运行 lint。已移除 serverRuntimeConfig/publicRuntimeConfig。
• 每个并行路由插槽都需要 default.tsx，否则构建会失败。
• next/image：priority 已弃用，请改用 preload；qualities 默认值为 [75]（其他 quality 值会被强制转换）；带查询字符串的本地 src 需要配置 images.localPatterns；images.domains 已弃用，请改用 remotePatterns。
• revalidateTag(tag) 已弃用；请传入 'max' 等配置文件，或 { expire: 0 } 以立即过期。updateTag 和 refresh 仅限 Server Action 使用。缓存详情：cache-components。

针对 next 16.3.8 检查过的 params 和 proxy 结构（next typegen、 tsc --noEmit、next build）：

// app/blog/[slug]/page.tsx; PageProps is global after `next typegen` (or dev/build)
export async function generateStaticParams() {
  return [{ slug: 'hello' }] // cacheComponents: needed for this top-level await; never []
}

export default async function Page({ params }: PageProps<'/blog/[slug]'>) {
  const { slug } = await params // a Promise; sync access was removed in 16
  return <h1>{slug}</h1>
}

// proxy.ts, replacing middleware.ts: Node.js runtime, no `runtime` export
import { NextResponse, type NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  // Optimistic check only: authorize again where the data is read.
  if (request.cookies.has('session')) return NextResponse.next()
  return NextResponse.redirect(new URL('/login', request.url))
}

export const config = { matcher: ['/dashboard/:path*'] }

upgrade codemod 不会迁移同步请求 API 的访问；迁移这部分代码时，请另外运行 next-async-request-api。请使用项目的包运行器，并检查生成的类型和运行时行为。

如需进行已获授权的升级，npx next@canary upgrade [app-dir] --agent=security （或 =latest；这是实验性功能，随 16.4 起在已安装的 02-guides/upgrading/agent-upgrade.md 中有文档说明）会选择目标版本，并为当前 Agent 输出升级指南、 codemod 和检查项；直接运行 next upgrade 则会启动交互式 codemod。

请针对实际故障或功能进行审查，而不是套用所有优化。 除非请求进行迁移，否则请保留项目的路由器、缓存模式、运行时和包管理器。

阅读受影响区域的相关内容

区域	本地参考资料
路由文件、分组、代理	文件约定
服务端/客户端导入和 props	RSC 边界、指令
参数和请求 API	异步 API、函数
读取、变更和 API	数据模式、路由处理程序
渲染和故障	Suspense、水合、错误
元数据和公开发现	元数据；使用 nextjs-seo 进行 SEO 审计
资源和加载	图像、字体、脚本
包和运行时行为	打包、运行时
导航插槽/模态框	并行路由
部署/调试	自托管、诊断

当启用该模式且与任务相关时，请使用 cache-components。 标签失效也可作用于该模式之外的 fetch 缓存。

使用项目的 lint/typecheck 脚本和生产构建进行验证， 然后在 next start 下测试已更改的路由。开发环境中的渲染可能会 掩盖预渲染/Suspense 问题；构建无法证明授权、水合、 新鲜度或跨实例行为。请报告实际测试过的内容。