Menu

代码转换工具

代码转换工具是对你的代码库进行程序化转换的工具。它允许在不需要手动修改每个文件的情况下，对大量代码进行程序化的修改。

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 Image 导入

next-image-to-legacy-image
Terminal
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>
  );
}

迁移到新的 Image 组件

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

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

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

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

new-link
Terminal
npx @next/codemod@latest new-link .

从 Link 组件 中移除 <a> 标签，或为无法自动修复的 Link 添加 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 特定功能。

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

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__ 目录 中找到。