什么是 Next.js 升级助手？

此技能通过提供结构化、自动化的框架维护方法，简化了升级 Next.js 应用程序这一通常很复杂的过程。通过利用 Openclaw Skills，开发人员可以自动检测其当前的项目环境，实时获取最新的官方迁移文档，并确定版本转换的最安全路径。

该技能侧重于通过智能应用官方 codemods 并确保 React 和 React DOM 等对等依赖项完全同步，来减少重大变更（breaking changes）带来的摩擦。无论您是从版本 13 迁移到 15，还是紧跟最新的实验性版本，此工具都能确保您的代码库遵循 Vercel 团队建立的官方最佳实践。

下载入口:https://github.com/openclaw/skills/tree/main/skills/tuanvidev/next-upgrade

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Next.js 升级助手 应用场景

• 将旧的 Next.js 13 或 14 项目迁移到最新的稳定版本。
• 在大型代码库中自动应用官方 Next.js codemods 以应对重大的 API 变更。
• 确保在框架跨版本升级期间，对等依赖项和 TypeScript 类型正确同步。
• 自动识别并修复 next.config.js 中已弃用的配置选项。

1. 扫描本地 package.json 以识别当前的 Next.js、React 和 React DOM 版本。
2. 使用 WebFetch 从 nextjs.org 获取最新的特定版本的迁移指南和 codemod 文档。
3. 确定是否需要增量升级路径（例如，在升级到 v15 之前先升级到 v14）以保持稳定性。
4. 通过 npx 执行相关的 codemods，以转换异步请求 API、地理位置/IP 属性和动态导入。
5. 使用项目的包管理器更新核心依赖项和 TypeScript 类型定义。
6. 对配置进行手动检查并运行构建检查以验证迁移是否成功。

Next.js 升级助手 配置指南

要在您的开发环境中使用此技能，请确保已安装 Openclaw Skills 框架。您可以通过运行以下命令启动升级序列：

# 运行 Next.js 升级工作流
openclaw run next-upgrade

该技能需要标准的 Node.js 环境，如果参数中未指定目标版本，则会提示输入。

Next.js 升级助手 数据架构与分类体系

该技能与项目元数据和远程文档的交互如下：

name: next-upgrade
description: Upgrade Next.js to the latest version following official migration guides and codemods
argument-hint: "[target-version]"

Upgrade Next.js

Upgrade the current project to the latest Next.js version following official migration guides.

Instructions

1. Detect current version: Read package.json to identify the current Next.js version and related dependencies (React, React DOM, etc.)

2. Fetch the latest upgrade guide: Use WebFetch to get the official upgrade documentation:

   • Codemods: https://nextjs.org/docs/app/guides/upgrading/codemods
   • Version-specific guides (adjust version as needed):
     • https://nextjs.org/docs/app/guides/upgrading/version-16
     • https://nextjs.org/docs/app/guides/upgrading/version-15
     • https://nextjs.org/docs/app/guides/upgrading/version-14

3. Determine upgrade path: Based on current version, identify which migration steps apply. For major version jumps, upgrade incrementally (e.g., 13 → 14 → 15).

4. Run codemods first: Next.js provides codemods to automate breaking changes:

   npx @next/codemod@latest  
   

   Common transforms:

   • next-async-request-api - Updates async Request APIs (v15)
   • next-request-geo-ip - Migrates geo/ip properties (v15)
   • next-dynamic-access-named-export - Transforms dynamic imports (v15)

5. Update dependencies: Upgrade Next.js and peer dependencies together:

   npm install next@latest react@latest react-dom@latest
   

6. Review breaking changes: Check the upgrade guide for manual changes needed:

   • API changes (e.g., async params in v15)
   • Configuration changes in next.config.js
   • Deprecated features being removed

7. Update TypeScript types (if applicable):

   npm install @types/react@latest @types/react-dom@latest
   

8. Test the upgrade:

   • Run npm run build to check for build errors
   • Run npm run dev and test key functionality