该技能用于 Next.js 16 应用开发,适用于创建页面、组件、布局、API 路由,实现 proxy.ts,以及为应用添加缓存等场景。资料给出的核心原则是:编写简洁、有针对性、DRY 的代码,采用现代 React 19 与 Next.js 16 模式。
一、Next.js 16 关键变更
- proxy.ts 替代 middleware.ts:middleware.ts 已弃用,应改用 proxy.ts(位于项目根目录或 src/)。proxy.ts 导出的函数名为 proxy(不再是 middleware),在 Node.js 运行时(非 Edge)执行。middleware.ts 仍向后兼容但即将弃用;若项目中已存在,应提及但不要重命名或改动。配置标志 skipMiddlewareUrlNormalize 改名为 skipProxyUrlNormalize。
- 异步请求 API(破坏性变更):所有请求 API 必须 await,包括 cookies()、headers()、draftMode()、params、searchParams。
- Turbopack 成为默认打包器,无需 --turbopack 标志;可用 --webpack 退出。配置从 experimental.turbopack 移至顶层 turbopack。
- Cache Components:新的缓存模型替代 experimental.ppr,通过 cacheComponents: true 启用,使用 "use cache" 指令进行显式缓存。
- 新缓存 API:updateTag(read-your-writes 语义,仅 Server Actions)、revalidateTag(现需 cacheLife 配置,如 revalidateTag('blog-posts', 'max'))、refresh(刷新未缓存数据,仅 Server Actions)。
二、React 19.2 特性与 React Compiler React 19.2 提供 View Transitions、useEffectEvent、<Activity>(display: none 的后台渲染)。React Compiler 已稳定,通过 reactCompiler: true 启用,需要安装 babel-plugin-react-compiler。
三、其他破坏性变更 Node.js 20.9+(不再支持 18)、TypeScript 5.1+;并行路由需要显式 default.js;next lint 移除,改用 ESLint;AMP 支持移除;next/legacy/image 弃用,改用 next/image;images.domains 弃用,改用 images.remotePatterns;next/image 默认值变化(minimumCacheTTL 60 秒改为 4 小时,imageSizes 默认数组移除 16,qualities 默认仅 [75],带查询字符串的本地图片需 images.localPatterns)。
四、编码规范 保持 DRY 与简洁,用最少代码解决问题,抽取重复模式为可复用组件或 hooks;文件保持在 300 行以内,接近上限时拆分;除非紧密耦合,每个文件一个组件。Next.js 16 模式:仅使用 App Router(app/ 目录);默认 Server Components,仅在确有必要时加 'use client';使用 Server Actions 处理变更;实现 loading.tsx 与 error.tsx 边界;使用 next/image、next/link、next/font。Tailwind CSS v4:使用 @import "tailwindcss"(非 v3 指令),通过 CSS 中 @theme 配置(非 tailwind.config.js),使用 bg-linear-to-r(非 bg-gradient-to-r),优先 CSS 变量而非 @apply。TypeScript:始终严格类型,使用 Id<'tableName'> 表示 Convex 文档 ID,定义显式返回类型,联合类型字符串字面量用 as const。
五、操作与研究 先阅读现有代码库,确保无重复代码;做外科手术式、有针对性的修改;保留代码库现有模式。遇到不熟悉的 Next.js 16 API 时,如可用则使用 Exa 与 Ref MCP 服务器搜索示例与官方文档;不可用时使用网络搜索工具。
限制与缺失:资料未提供该技能的安装方式、命令、收费或平台信息。