代码修改工具 (Codemods)

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

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

使用方法

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

终端

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

将 <转换名称> 和 <路径> 替换为适当的值。

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

Next.js 代码修改工具

13.2 版本

使用内置字体

`built-in-next-font`

终端

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`

终端

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

安全地将现有 Next.js 10、11 或 12 应用中的 next/image 导入重命名为 Next.js 13 中的 next/legacy/image。同时将 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`

终端

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

危险地将 next/legacy/image 迁移至新的 next/image，通过添加内联样式并移除未使用的属性。

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

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

`new-link`

终端

npx @next/codemod@latest new-link .

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

例如：

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

<Link href="/about">
  <a onClick={() => console.log('点击')}>关于</a>
</Link>
// 转换为
<Link href="/about" onClick={() => console.log('点击')}>
  关于
</Link>

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

const Component = () => <a>关于</a>

<Link href="/about">
  <Component />
</Link>
// 变为
<Link href="/about" legacyBehavior>
  <Component />
</Link>

11 版本

从 CRA 迁移

`cra-to-next`

终端

npx @next/codemod cra-to-next

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

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

10 版本

添加 React 导入

`add-missing-react-import`

终端

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`

终端

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`

终端

npx @next/codemod withamp-to-config

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

例如：

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

function Home() {
  return <h1>我的 AMP 页面</h1>
}

export default withAmp(Home)

// 转换后
export default function Home() {
  return <h1>我的 AMP 页面</h1>
}

export const config = {
  amp: true,
}

6 版本

使用 `withRouter`

`url-to-withrouter`

终端

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>当前路径: {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>当前路径: {pathname}</div>
    }
  }
)

这是一个转换示例。所有转换情况（及测试用例）可在 __testfixtures__ 目录中找到。

On this page