Next.js 项目升级指南：使用 Codemods 自动化代码迁移

什么是 Codemods？

Codemods 是一种程序化代码转换工具，它能够自动对代码库进行批量修改，无需开发者手动逐个文件调整。在 Next.js 生态系统中，Codemods 被设计用来帮助开发者平滑升级项目代码，特别是当 API 更新或废弃时。

为什么需要 Codemods？

随着 Next.js 版本的迭代，框架会引入新特性或调整现有 API。手动更新大型项目中的相关代码既耗时又容易出错。Codemods 提供了一种安全、高效的升级方式：

1. 减少人为错误：自动化转换比手动修改更可靠
2. 提高效率：可一次性处理整个项目
3. 保持一致性：确保所有文件采用相同的更新方式

基本使用方法

在项目根目录下执行以下命令：

npx @next/codemod <转换名称> <路径>

常用参数说明：

• --dry：模拟运行，不实际修改代码
• --print：输出变更对比，方便检查

主要 Codemods 转换介绍

15.0 版本相关转换

1. 应用路由运行时配置更新

将应用路由中的 runtime: 'experimental-edge' 更新为标准的 edge 运行时：

npx @next/codemod@latest app-dir-runtime-config-experimental-edge .

转换示例：

// 转换前
export const runtime = 'experimental-edge'

// 转换后
export const runtime = 'edge'

2. 动态 API 异步化迁移

Next.js 15 中，部分动态 API 变为异步操作，此转换会自动添加必要的 await 或 React.use()：

npx @next/codemod@latest next-async-request-api .

典型转换场景包括：

• cookies() 相关操作
• headers() 相关操作
• draftMode() 相关操作

3. 地理位置和 IP 处理更新

迁移 NextRequest 中的 geo 和 ip 属性到 @vercel/functions 包：

npx @next/codemod@latest next-request-geo-ip .

转换示例：

// 转换前
import type { NextRequest } from 'next/server'
export function GET(req: NextRequest) {
  const { geo, ip } = req
}

// 转换后
import type { NextRequest } from 'next/server'
import { geolocation, ipAddress } from '@vercel/functions'
export function GET(req: NextRequest) {
  const geo = geolocation(req)
  const ip = ipAddress(req)
}

14.0 版本相关转换

1. ImageResponse 导入路径更新

npx @next/codemod@latest next-og-import .

将 next/server 中的 ImageResponse 导入更新为 next/og。

2. 元数据到 viewport 导出迁移

npx @next/codemod@latest metadata-to-viewport-export .

将特定 viewport 相关元数据移动到独立的 viewport 导出。

13.0 版本相关转换

1. 图片组件导入更新

npx @next/codemod@latest next-image-to-legacy-image .

将旧版图片导入路径更新：

• next/image → next/legacy/image
• next/future/image → next/image

2. 链接组件优化

npx @next/codemod@latest new-link .

移除 Link 组件内冗余的 <a> 标签，或在无法自动修复时添加 legacyBehavior 属性。

使用建议

1. 先做模拟运行：使用 --dry 参数检查转换效果
2. 版本对应：确保使用与目标 Next.js 版本匹配的 codemod
3. 代码审查：转换后仔细检查关键业务逻辑
4. 测试验证：运行完整测试套件确保功能正常

注意事项

• 某些复杂场景可能需要手动调整，转换工具会添加 @next/codemod 注释提示
• 类型转换会使用 UnsafeUnwrapped 前缀标记需要检查的位置
• 建议在版本升级前先完成代码转换

通过合理使用这些 Codemods，开发者可以显著降低 Next.js 版本升级的工作量和风险，让项目保持与技术前沿同步的同时，确保代码质量和稳定性。