代码修改工具 (Codemods)

代码修改工具 (codemods) 是通过编程方式对代码库进行转换的工具。这使得无需手动检查每个文件即可批量应用大量变更。

Next.js 提供代码修改转换工具，帮助您在 API 更新或弃用时升级 Next.js 代码库。

使用方法

在终端中，进入 (cd) 项目文件夹后运行：

Terminal

npx @next/codemod <transform> <path>

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

transform - 转换名称
path - 要转换的文件或目录
--dry 试运行，不会实际修改代码
--print 打印变更后的输出用于比较

Next.js 代码修改工具

14.0

迁移 `ImageResponse` 导入

`next-og-import`

Terminal

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

此代码修改工具将动态 OG 图片生成相关的导入从 next/server 迁移至 next/og。

例如：

import { ImageResponse } from 'next/server'

转换为：

import { ImageResponse } from 'next/og'

使用 `viewport` 导出

`metadata-to-viewport-export`

Terminal

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

此代码修改工具将部分视口元数据迁移至 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`

Terminal

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

此代码修改工具会卸载 @next/font 包，并将 @next/font 导入转换为内置的 next/font。

例如：

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

转换为：

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

13.0

重命名 Next 图片导入

`next-image-to-legacy-image`

Terminal

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

安全地将 Next.js 10、11 或 12 应用中的 next/image 导入重命名为 next/legacy/image（适用于 Next.js 13）。同时将 next/future/image 重命名为 next/image。

例如：

pages/index.js

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>
  )
}

转换为：

pages/index.js

// 'next/image' 变为 'next/legacy/image'
import Image1 from 'next/legacy/image'
// 'next/future/image' 变为 '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>
  )
}

迁移至新版图片组件

`next-image-experimental`

Terminal

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

危险操作：通过添加内联样式和移除未使用的属性，从 next/legacy/image 迁移至新版 next/image。

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

移除链接组件中的 `<a>` 标签

`new-link`

Terminal

npx @next/codemod@latest new-link .

移除链接组件中的 <a> 标签，或为无法自动修复的链接添加 legacyBehavior 属性。

例如：

<Link href="/about">
  <a>About</a>
</Link>
// 转换为
<Link href="/about">
  About
</Link>

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

对于无法自动修复的情况，会添加 legacyBehavior 属性。这允许您的应用针对特定链接继续使用旧有行为。

const Component = () => <a>About</a>

<Link href="/about">
  <Component />
</Link>
// 转换为
<Link href="/about" legacyBehavior>
  <Component />
</Link>

11

从 CRA 迁移

`cra-to-next`

Terminal

npx @next/codemod cra-to-next

将 Create React App 项目迁移至 Next.js；创建页面路由 (Pages Router) 和必要的配置以匹配行为。初始阶段会利用客户端渲染来防止因 SSR 期间使用 window 导致的兼容性问题，后续可以无缝启用以逐步采用 Next.js 特有功能。

请在此讨论中分享与此转换相关的任何反馈：https://github.com/vercel/next.js/discussions/25858。

10

添加 React 导入

`add-missing-react-import`

Terminal

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

转换未导入 React 的文件，使其包含导入语句以支持新的 React JSX 转换。

例如：

my-component.js

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

转换为：

my-component.js

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

9

将匿名组件转换为命名组件

`name-default-component`

Terminal

npx @next/codemod name-default-component

适用于 9 及以上版本。

将匿名组件转换为命名组件，确保它们与快速刷新 (Fast Refresh) 兼容。

例如：

my-component.js

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

转换为：

my-component.js

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

组件将基于文件名获得驼峰式命名，此转换也适用于箭头函数。

8

将 AMP HOC 转换为页面配置

`withamp-to-config`

Terminal

npx @next/codemod withamp-to-config

将 withAmp 高阶组件 (HOC) 转换为 Next.js 9 的页面配置。

例如：

// 转换前
import { withAmp } from 'next/amp'

function Home() {
  return <h1>My AMP Page</h1>
}

export default withAmp(Home)

// 转换后
export default function Home() {
  return <h1>My AMP Page</h1>
}

export const config = {
  amp: true,
}

6

使用 `withRouter`

`url-to-withrouter`

Terminal

npx @next/codemod url-to-withrouter

将顶级页面中已弃用的自动注入 url 属性转换为使用 withRouter 及其注入的 router 属性。了解更多：https://nextjs.org/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__ 目录中找到。

On this page