代码修改器

Codemods 是在您的代码库上以编程方式运行的转换。这允许以编程方式应用大量更改，而无需手动逐个文件地进行操作。

Next.js 提供了 Codemod 转换，以帮助您在 API 更新或弃用时升级 Next.js 代码库。

用法

在您的终端中，导航 (cd) 到您的项目文件夹，然后运行

npx @next/codemod <transform> <path>

将 <transform> 和 <path> 替换为适当的值。

transform - 转换名称
path - 要转换的文件或目录
--dry 执行试运行，不编辑任何代码
--print 打印更改后的输出以进行比较

Codemods

16.0

从 App Router 页面和布局中移除 `experimental_ppr` 路由段配置

`移除-experimental-ppr`

npx @next/codemod@latest remove-experimental-ppr .

此 codemod 从 App Router 页面和布局中移除 experimental_ppr 路由段配置。

- export const experimental_ppr = true;

从稳定 API 中移除 `unstable_` 前缀

`移除-unstable-前缀`

npx @next/codemod@latest remove-unstable-prefix .

此 codemod 从稳定 API 中移除 unstable_ 前缀。

例如

import { unstable_cacheTag as cacheTag } from 'next/cache'
 
cacheTag()

转换为

import { cacheTag } from 'next/cache'
 
cacheTag()

从已废弃的 `middleware` 约定迁移到 `proxy`

`middleware-to-proxy`

npx @next/codemod@latest middleware-to-proxy .

此 codemod 将项目从使用已弃用的 middleware 约定迁移到使用 proxy 约定。它

将 middleware.<extension> 重命名为 proxy.<extension>（例如，middleware.ts 重命名为 proxy.ts）
将命名导出 middleware 重命名为 proxy
将 Next.js 配置属性 experimental.middlewarePrefetch 重命名为 experimental.proxyPrefetch
将 Next.js 配置属性 experimental.middlewareClientMaxBodySize 重命名为 experimental.proxyClientMaxBodySize
将 Next.js 配置属性 experimental.externalMiddlewareRewritesResolve 重命名为 experimental.externalProxyRewritesResolve
将 Next.js 配置属性 skipMiddlewareUrlNormalize 重命名为 skipProxyUrlNormalize

例如

import { NextResponse } from 'next/server'
 
export function middleware() {
  return NextResponse.next()
}

转换为

import { NextResponse } from 'next/server'
 
export function proxy() {
  return NextResponse.next()
}

从 `next lint` 迁移到 ESLint CLI

`next-lint-to-eslint-cli`

npx @next/codemod@canary next-lint-to-eslint-cli .

此 codemod 将项目从使用 next lint 迁移到使用带有本地 ESLint 配置的 ESLint CLI。它

创建一个带有 Next.js 推荐配置的 eslint.config.mjs 文件
更新 package.json 脚本以使用 eslint . 而不是 next lint
向 package.json 添加必要的 ESLint 依赖项
保留现有的 ESLint 配置（如果找到）

例如

{
  "scripts": {
    "lint": "next lint"
  }
}

变成

{
  "scripts": {
    "lint": "eslint ."
  }
}

并创建

import { dirname } from 'path'
import { fileURLToPath } from 'url'
import { FlatCompat } from '@eslint/eslintrc'
 
const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)
 
const compat = new FlatCompat({
  baseDirectory: __dirname,
})
 
const eslintConfig = [
  ...compat.extends('next/core-web-vitals', 'next/typescript'),
  {
    ignores: [
      'node_modules/**',
      '.next/**',
      'out/**',
      'build/**',
      'next-env.d.ts',
    ],
  },
]
 
export default eslintConfig

15.0

将 App Router 路由段配置 `runtime` 值从 `experimental-edge` 转换为 `edge`

`app-dir-runtime-config-experimental-edge`

注意：此 codemod 仅适用于 App Router。

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

此 codemod 将路由段配置 runtime 值 experimental-edge 转换为 edge。

例如

export const runtime = 'experimental-edge'

转换为

export const runtime = 'edge'

迁移到异步动态 API

以前支持同步访问的动态渲染 API 现在是异步的。您可以在升级指南中阅读有关此重大更改的更多信息。

`next-async-request-api`

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

此 codemod 将现在是异步的动态 API（来自 next/headers 的 cookies()、headers() 和 draftMode()）转换为正确地 await 或（如果适用）使用 React.use() 包装。当无法自动迁移时，codemod 将添加类型转换（如果是 TypeScript 文件）或注释以通知用户需要手动检查和更新。

例如

import { cookies, headers } from 'next/headers'
const token = cookies().get('token')
 
function useToken() {
  const token = cookies().get('token')
  return token
}
 
export default function Page() {
  const name = cookies().get('name')
}
 
function getHeader() {
  return headers().get('x-foo')
}

转换为

import { use } from 'react'
import {
  cookies,
  headers,
  type UnsafeUnwrappedCookies,
  type UnsafeUnwrappedHeaders,
} from 'next/headers'
const token = (cookies() as unknown as UnsafeUnwrappedCookies).get('token')
 
function useToken() {
  const token = use(cookies()).get('token')
  return token
}
 
export default async function Page() {
  const name = (await cookies()).get('name')
}
 
function getHeader() {
  return (headers() as unknown as UnsafeUnwrappedHeaders).get('x-foo')
}

当我们检测到页面/路由入口（page.js、layout.js、route.js 或 default.js）或 generateMetadata / generateViewport API 中的 params 或 searchParams 属性访问时，它将尝试将调用点从同步函数转换为异步函数，并 await 属性访问。如果无法将其设为异步（例如客户端组件），它将使用 React.use 解开 Promise。

例如

// page.tsx
export default function Page({
  params,
  searchParams,
}: {
  params: { slug: string }
  searchParams: { [key: string]: string | string[] | undefined }
}) {
  const { value } = searchParams
  if (value === 'foo') {
    // ...
  }
}
 
export function generateMetadata({ params }: { params: { slug: string } }) {
  const { slug } = params
  return {
    title: `My Page - ${slug}`,
  }
}

转换为

// page.tsx
export default async function Page(props: {
  params: Promise<{ slug: string }>
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
  const searchParams = await props.searchParams
  const { value } = searchParams
  if (value === 'foo') {
    // ...
  }
}
 
export async function generateMetadata(props: {
  params: Promise<{ slug: string }>
}) {
  const params = await props.params
  const { slug } = params
  return {
    title: `My Page - ${slug}`,
  }
}

须知： 当此 codemod 发现可能需要手动干预但我们无法确定确切修复的位置时，它将向代码添加注释或类型转换，以通知用户需要手动更新。这些注释以 @next/codemod 为前缀，类型转换以 UnsafeUnwrapped 为前缀。在明确删除这些注释之前，您的构建将出错。阅读更多。

用 `@vercel/functions` 替换 `NextRequest` 的 `geo` 和 `ip` 属性

`next-request-geo-ip`

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

此 codemod 安装 @vercel/functions 并将 NextRequest 的 geo 和 ip 属性转换为相应的 @vercel/functions 功能。

例如

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

迁移 `ImageResponse` 导入

`next-og-import`

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

此 codemod 将 next/server 的导入转换为 next/og，以便使用动态 OG 图像生成。

例如

import { ImageResponse } from 'next/server'

转换为

import { ImageResponse } from 'next/og'

使用 `viewport` 导出

`metadata-to-viewport-export`

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

此 codemod 将某些视口元数据迁移到 viewport 导出。

例如

export const metadata = {
  title: 'My App',
  themeColor: 'dark',
  viewport: {
    width: 1,
  },
}

转换为

export const metadata = {
  title: 'My App',
}
 
export const viewport = {
  width: 1,
  themeColor: 'dark',
}

13.2

使用内置字体

`built-in-next-font`

npx @next/codemod@latest built-in-next-font .

此 codemod 卸载 @next/font 包，并将 @next/font 导入转换为内置的 next/font。

例如

import { Inter } from '@next/font/google'

转换为

import { Inter } from 'next/font/google'

13.0

重命名 Next Image 导入

`next-image-to-legacy-image`

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

在 Next.js 13 中，安全地将现有 Next.js 10、11 或 12 应用程序中的 next/image 导入重命名为 next/legacy/image。还重命名 next/future/image 为 next/image。

例如

import Image1 from 'next/image'
import Image2 from 'next/future/image'
 
export default function Home() {
  return (
    <div>
      <Image1 src="/test.jpg" width="200" height="300" />
      <Image2 src="/test.png" width="500" height="400" />
    </div>
  )
}

转换为

// 'next/image' becomes 'next/legacy/image'
import Image1 from 'next/legacy/image'
// 'next/future/image' becomes 'next/image'
import Image2 from 'next/image'
 
export default function Home() {
  return (
    <div>
      <Image1 src="/test.jpg" width="200" height="300" />
      <Image2 src="/test.png" width="500" height="400" />
    </div>
  )
}

迁移到新的 Image 组件

`next-image-experimental`

npx @next/codemod@latest next-image-experimental .

通过添加内联样式和移除未使用的 props，危险地从 next/legacy/image 迁移到新的 next/image。

移除 layout 属性并添加 style。
移除 objectFit 属性并添加 style。
移除 objectPosition 属性并添加 style。
移除 lazyBoundary 属性。
移除 lazyRoot 属性。

从 Link 组件中移除 `<a>` 标签

`new-link`

npx @next/codemod@latest new-link .

移除Link 组件中的 <a> 标签。

例如

<Link href="/about">
  <a>About</a>
</Link>
// transforms into
<Link href="/about">
  About
</Link>
 
<Link href="/about">
  <a onClick={() => console.log('clicked')}>About</a>
</Link>
// transforms into
<Link href="/about" onClick={() => console.log('clicked')}>
  About
</Link>

11

从 CRA 迁移

`cra-to-next`

npx @next/codemod cra-to-next

将 Create React App 项目迁移到 Next.js；创建一个 Pages Router 和必要的配置以匹配行为。最初利用仅客户端渲染，以防止由于 SSR 期间的 window 使用而导致兼容性问题，并且可以无缝启用以允许逐步采用 Next.js 特定功能。

请在此讨论中分享与此转换相关的任何反馈。

npx @next/codemod add-missing-react-import

转换不导入 React 的文件，以包含导入，以便新的React JSX 转换工作。

例如

export default class Home extends React.Component {
  render() {
    return <div>Hello World</div>
  }
}

转换为

import React from 'react'
export default class Home extends React.Component {
  render() {
    return <div>Hello World</div>
  }
}

npx @next/codemod name-default-component

版本 9 及以上。

将匿名组件转换为命名组件，以确保它们与快速刷新配合使用。

例如

export default function () {
  return <div>Hello World</div>
}

转换为

export default function MyComponent() {
  return <div>Hello World</div>
}

组件将根据文件名具有驼峰式命名，并且它也适用于箭头函数。

8

注意：内置 AMP 支持和此 codemod 已在 Next.js 16 中移除。

将 AMP HOC 转换为页面配置

`withamp-to-config`

npx @next/codemod withamp-to-config

将 withAmp HOC 转换为 Next.js 9 页面配置。

例如

// Before
import { withAmp } from 'next/amp'
 
function Home() {
  return <h1>My AMP Page</h1>
}
 
export default withAmp(Home)

// After
export default function Home() {
  return <h1>My AMP Page</h1>
}
 
export const config = {
  amp: true,
}

npx @next/codemod url-to-withrouter

将顶级页面上已弃用的自动注入 url 属性转换为使用 withRouter 及其注入的 router 属性。在此处阅读更多信息：https://nextjs.net.cn/docs/messages/url-deprecated

例如

import React from 'react'
export default class extends React.Component {
  render() {
    const { pathname } = this.props.url
    return <div>Current pathname: {pathname}</div>
  }
}

import React from 'react'
import { withRouter } from 'next/router'
export default withRouter(
  class extends React.Component {
    render() {
      const { pathname } = this.props.router
      return <div>Current pathname: {pathname}</div>
    }
  }
)

这是一个案例。所有已转换（并测试过）的案例都可以在__testfixtures__ 目录中找到。