跳至内容

代码修改器

代码修改器是通过编程方式在您的代码库上运行的转换。这允许以编程方式应用大量更改,而无需手动检查每个文件。

当 API 更新或弃用时,Next.js 提供代码修改器转换来帮助升级您的 Next.js 代码库。

用法

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

终端
npx @next/codemod <transform> <path>

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

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

代码修改

15.0

将应用路由器路由段配置 runtime 值从 experimental-edge 转换为 edge

app-dir-runtime-config-experimental-edge

注意:此代码修改特定于应用路由器。

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

此代码修改将 路由段配置 runtimeexperimental-edge 转换为 edge

例如

export const runtime = 'experimental-edge'

转换为

export const runtime = 'edge'

迁移到异步动态 API 升级指南中阅读有关此重大更改的更多信息。

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

此代码修改将现在异步的动态 API(来自 next/headerscookies()headers()draftMode())转换为适当的 await 或用 React.use() 包装(如果适用)。当无法自动迁移时,代码修改将添加类型转换(如果是 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 } from 'next/headers'
 
const token = (await cookies()).get('token')
 
function useToken() {
  const token = use(cookies()).get('token')
  return token
}
 
export default function Page() {
  const name = (await cookies()).get('name')
}
 
function getHeader() {
  return (headers() as UnsafeUnwrappedCookies).get('x-foo')
}

当我们在页面/路由条目(page.jslayout.jsroute.jsdefault.js)或 generateMetadata/generateViewport API 中检测到对 paramssearchParams 属性的属性访问时,它将尝试将调用站点从同步函数转换为异步函数,并等待属性访问。如果无法使其异步(例如使用客户端组件),它将使用 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 } }) {
  return {
    title: `My Page - ${slug}`,
  }
}

转换为

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

温馨提示:当此代码修改识别出可能需要手动干预但我们无法确定确切修复方法的位置时,它会在代码中添加注释或类型转换以通知用户需要手动更新。这些注释以 @next/codemod 为前缀,类型转换以 UnsafeUnwrapped 为前缀。您的构建将出错,直到明确删除这些注释。阅读更多

NextRequestgeoip 属性替换为 @vercel/functions next-request-geo-ip
终端
npx @next/codemod@latest next-request-geo-ip .

此代码修改安装 @vercel/functions 并使用相应的 @vercel/functions 功能转换 NextRequestgeoip 属性。

例如

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

将访问命名导出的 next/dynamic 导入转换为返回带有 default 属性的对象 next-dynamic-access-named-export
终端
npx @next/codemod@latest next-dynamic-access-named-export .

此代码修改会转换使用 next/dynamic 的动态导入,以确保它们在访问命名导出时返回带有 default 属性的对象。这使行为与 React.lazy 保持一致,并解决了从服务器组件中的客户端组件访问命名导出时出现的问题。

例如

import dynamic from 'next/dynamic'
 
const ComponentA = dynamic(() =>
  import('../components/a').then((mod) => mod.default)
)
 
const ComponentB = dynamic(() =>
  import('../components/b').then((mod) => mod.ComponentB)
)

转换为

import dynamic from 'next/dynamic'
 
const ComponentA = dynamic(() =>
  import('../components/a').then((mod) => ({ default: mod.default }))
)
 
const ComponentB = dynamic(() =>
  import('../components/b').then((mod) => ({ default: mod.ComponentB }))
)

温馨提示:此代码修改仅影响使用 next/dynamic 并访问命名导出的动态导入。

14.0

迁移 ImageResponse 导入 next-og-import

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

此代码修改将变换导入从 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 .

此代码修改将某些视口元数据迁移到 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 .

此代码修改将卸载 @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

例如

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' 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 .

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

终端
npx @next/codemod@latest new-link .

删除Link 组件内的 <a> 标签,或者向无法自动修复的 Link 添加 legacyBehavior 属性。

例如

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

在无法应用自动修复的情况下,将添加 legacyBehavior 属性。这允许您的应用程序继续使用该特定链接的旧行为。

const Component = () => <a>About</a>
 
<Link href="/about">
  <Component />
</Link>
// becomes
<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 及以上。

将匿名组件转换为命名组件,以确保它们与 快速刷新 协同工作。

例如

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 页面配置。

例如

// 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,
}

6

使用 withRouter url-to-withrouter
终端
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__ 目录 中找到。