mcpField
N
nextjs16-skills

nextjs16-skills

github.com/gocallum开发23715 次安装40 周前更新
代码仓库

关于 nextjs16-skills

nextjs16-skills 汇总 Next.js 16 的升级、功能变化和迁移要点，面向维护或构建 Next.js 项目的开发者。内容涵盖缓存、Turbopack、路由变化及兼容性要求。

主要功能

  1. 01Next.js 16 升级指引
  2. 02缓存 API 与 Cache Components
  3. 03Turbopack 配置和迁移
  4. 04路由与预取变化
  5. 05破坏性变更和弃用项

适用场景

  1. 01将 Next.js 项目升级到 v16
  2. 02迁移 Webpack 或 Turbopack 配置
  3. 03调整缓存与重新验证逻辑
  4. 04检查升级中的兼容性变化

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/gocallum/nextjs16-agent-skills --skill nextjs16-skills

安装后在 Claude Code 中输入/nextjs16-skills确认已加载。

详细介绍

链接

升级

# Automated upgrade
npx @next/codemod@canary upgrade latest

# Manual upgrade
npm install next@latest react@latest react-dom@latest

# New project
npx create-next-app@latest

Codemod 涵盖的内容（概览）：迁移 Turbopack 配置，将 next lint 迁移到 ESLint CLI，将 middleware 迁移到 proxy，移除部分 unstable_ 前缀，并移除路由级别的 experimental_ppr。

TypeScript：同时升级 @types/react 和 @types/react-dom。

新特性（v16）

  • Cache Components：通过 "use cache" 指令启用缓存；演进并整合 PPR。
  • Next.js DevTools MCP：集成 Model Context Protocol，支持 AI 辅助调试。
  • proxy.ts：网络边界更清晰；middleware.ts 在大多数场景中已弃用。
  • 更完善的日志／指标：next dev 和构建过程会输出更详细的计时信息。

性能／开发体验

  • Turbopack：已稳定；默认打包器（可通过 next dev --webpack、next build --webpack 选择退出）。
  • 如果你有自定义 webpack 配置，next build 可能会失败（以防止配置错误）。可通过迁移配置、使用 next build --webpack，或改用 Turbopack 并移除／忽略 webpack 配置来解决。
  • Turbopack 配置已迁移：在 next.config.* 中从 experimental.turbopack 移至顶层的 turbopack。
  • Turbopack 迁移注意事项：
    • Sass 导入：移除仅适用于 Webpack 的 ~ 前缀（例如 @import 'bootstrap/...';）。
    • 浏览器端打包内容不得导入 Node 内置模块（例如 fs）。若无法避免，可暂时使用 turbopack.resolveAlias。
  • Turbopack 文件系统缓存（开发环境，测试版）：experimental.turbopackFileSystemCacheForDev: true。
  • React Compiler 支持：可通过 reactCompiler: true 稳定地选择启用（请注意构建／编译开销会更高）。
  • Build Adapters API：alpha 阶段（自定义构建适配器）。
  • 路由／预取重写：布局去重 + 增量预取。

缓存 API（关键签名）

  • revalidateTag(tag, profile) 现在需要 cacheLife 配置文件（或 { expire }）才能实现 SWR 行为。
  • updateTag(tag)（仅限 Server Actions）：实现读后写语义。
  • refresh()（仅限 Server Actions）：刷新未缓存的数据；不会修改缓存。
  • cacheLife 和 cacheTag 已稳定（不再带 unstable_ 前缀）。

要求（v16）

  • Node.js：20.9+
  • TypeScript：5.1+
  • 浏览器：Chrome／Edge／Firefox 111+，Safari 16.4+

破坏性／行为变更（影响较大）

  • 异步 Request API：已移除同步访问方式。请使用 await params、await searchParams、await cookies()、await headers()、await draftMode()。
  • 提示（TypeScript）：npx next typegen 可生成 PageProps、LayoutProps、RouteContext 等辅助类型，以安全迁移 params/searchParams 类型。
  • 元数据图片：在图片函数中，opengraph-image、twitter-image、icon、apple-icon 现在接收 Promise 类型的 params（以及 id）。
  • 站点地图：使用 generateSitemaps 时，sitemap({ id }) 现在接收 Promise 类型的 id。
  • 并行路由：插槽必须显式提供 default.js。
  • next/image 默认值已更改（缓存 TTL、尺寸／质量）；带查询字符串的本地 src 需要配置 images.localPatterns。

其他值得注意的行为变更：

  • next dev 和 next build 使用不同的输出目录（next dev → .next/dev），并通过锁文件阻止并发实例运行。
  • 滚动行为：Next.js 在导航期间不再覆盖全局 scroll-behavior: smooth；在 <html> 上添加 data-scroll-behavior="smooth" 可恢复之前的覆盖行为。
  • ESLint：@next/eslint-plugin-next 默认使用 ESLint Flat Config；使用旧版 .eslintrc 的项目可能需要迁移。

已移除 / 已弃用（概述）

  • 已移除：AMP 支持；next lint（请直接使用 ESLint/Biome）；next.config.* 中的 eslint 选项；serverRuntimeConfig/publicRuntimeConfig（请使用环境变量）；experimental.ppr 和路由级别的 experimental_ppr；unstable_rootParams。
  • 已弃用：middleware.ts 文件名（建议使用 proxy.ts）；next/legacy/image；images.domains（建议使用 images.remotePatterns）；revalidateTag(tag) 单参数形式。
  • proxy.ts 说明：proxy 仅在 nodejs 上运行；proxy 不支持 Edge 运行时。如果必须使用 Edge，请保留 middleware.ts。
  • 配置重命名示例：skipMiddlewareUrlNormalize → skipProxyUrlNormalize。

评论

支持 Markdown