chakra-ui-migrate

Chakra UI 迁移：v2 → v3

你正在指导一位开发者将其项目从 Chakra UI v2 迁移到 v3。请按顺序完成以下步骤。先检查项目——绝不要猜测包版本或框架。

Node 要求： Chakra UI v3 要求 Node >= 20.x。如果环境不确定，请在继续之前确认。

---

第 1 步 — 检查项目

阅读以下文件以了解当前状态：

package.json

查找：

• 当前的 @chakra-ui/react 版本（v2.x 还是 v3.x）
• 相关包：@chakra-ui/icons、@chakra-ui/hooks、@chakra-ui/next-js、@emotion/styled、framer-motion
• 框架：Next.js（App Router 或 Pages Router）、Vite、纯 React
• 包管理器（从 lockfile 判断：pnpm-lock.yaml、yarn.lock、bun.lock、package-lock.json）

在有帮助时，也抽查关键文件：

• Provider / 主题设置（_app.tsx、layout.tsx、theme.ts）
• 颜色模式的使用（ColorModeScript、useColorMode、useColorModeValue）
• 任何显示出大量 v2 模式的组件文件

---

第 2 步 — 更新包

移除仅 v2 使用的依赖

# npm
npm uninstall @chakra-ui/icons @chakra-ui/hooks @chakra-ui/next-js @emotion/styled framer-motion

# pnpm
pnpm remove @chakra-ui/icons @chakra-ui/hooks @chakra-ui/next-js @emotion/styled framer-motion

# yarn
yarn remove @chakra-ui/icons @chakra-ui/hooks @chakra-ui/next-js @emotion/styled framer-motion

@emotion/styled 和 framer-motion 在 v3 中不再需要。

安装 v3 核心包

# npm
npm install @chakra-ui/react @emotion/react

# pnpm
pnpm add @chakra-ui/react @emotion/react

# yarn
yarn add @chakra-ui/react @emotion/react

已移除包的替代方案

已移除	替代方案
@chakra-ui/icons	lucide-react 或 react-icons
@chakra-ui/hooks	react-use 或 usehooks-ts
@chakra-ui/next-js	asChild prop 模式（见 Next.js 章节）

---

第 3 步 — 运行 codemod

官方 codemod 处理大多数机械性更改：组件重命名、prop 更新、import 重写以及复合组件重构。它不能替代人工审查——请计划对输出进行审核。

先进行试运行（不更改文件）：

npx @chakra-ui/codemod upgrade --dry

查看它建议的内容。满意后：

npx @chakra-ui/codemod upgrade

codemod 运行后，在进行手动编辑之前先提交更改，这样你就有一个干净的 diff 可供使用。

---

第 4 步 — 更新 Provider

旧的 v2 模式

// v2
import { ChakraProvider } from "@chakra-ui/react"
import theme from "./theme"

;<ChakraProvider theme={theme}>{children}</ChakraProvider>

新的 v3 模式（使用 Chakra CLI snippets）

生成 provider 和组件 snippets：

npx @chakra-ui/cli snippet add

这会创建 components/ui/provider.tsx（以及 toaster 和 tooltip snippets），并自动安装所需的 npm 依赖——包括 next-themes。导入并使用它：

// v3 — app/layout.tsx (Next.js App Router)
import { Provider } from "@/components/ui/provider"

;<html lang="en" suppressHydrationWarning>
  <body>
    <Provider>{children}</Provider>
  </body>
</html>

Provider 文件包含 "use client"——不要将其添加到 layout.tsx 中。关于 Pages Router 的放置位置，见 Next.js 章节。

v3 中的自定义主题

用 createSystem 替换 extendTheme：

// v2
import { extendTheme } from "@chakra-ui/react"
// v3
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"

export const theme = extendTheme({ colors: { brand: { 500: "#2196f3" } } })

const config = defineConfig({
  theme: { tokens: { colors: { brand: { 500: { value: "#2196f3" } } } } },
})
export const system = createSystem(defaultConfig, config)

通过 value={system} 将 system 传递给 ChakraProvider。

---

第 5 步 — 颜色模式迁移

移除所有 v2 颜色模式模式

// REMOVE these v2 imports and usages:
import { ColorModeScript } from "@chakra-ui/react"
// ❌
import { useColorMode } from "@chakra-ui/react"
// ❌ (use next-themes)
import { useColorModeValue } from "@chakra-ui/react"
// ❌ (use CSS tokens)
import { DarkMode, LightMode } from "@chakra-ui/react"

// ❌

// Also remove from _document.tsx:
;<ColorModeScript initialColorMode={theme.config.initialColorMode} /> // ❌

v3 颜色模式方法

颜色模式由 next-themes 通过生成的 Provider 处理。使用能自动响应当前活动颜色模式的语义 token：

// Use Chakra semantic tokens — they flip automatically in dark mode
<Box color="fg.default" bg="bg.subtle">
  ...
</Box>

如需颜色模式切换，请使用生成的 components/ui/color-mode.tsx snippet，或直接使用 next-themes 中的 useColorMode。

---

第 6 步 — Prop 重命名

这些布尔和样式 prop 在 v3 中为了与 HTML 和现代 React 约定保持一致而重命名。codemod 会捕获其中的大部分，但之后仍需手动核实。

布尔 props

v2	v3
isOpen	open
defaultIsOpen	defaultOpen
isDisabled	disabled
isInvalid	invalid
isRequired	required
isReadOnly	readOnly
isChecked	checked
isLoaded	loaded
isIndeterminate	indeterminate

样式与布局 props

v2	v3
colorScheme	colorPalette
noOfLines	lineClamp
truncated	truncate
spacing (Stack)	gap
apply	textStyle 或 layerStyle

嵌套样式 props

// v2 — sx with nested pseudo-selectors
<Box sx={{ "&:hover": { color: "blue.500" } }} />

// v3 — css prop with "&" selectors
<Box css={{ "&:hover": { color: "blue.500" } }} />

---

第 7 步 — 组件迁移

重命名的组件

v2	v3
Modal	Dialog
FormControl	Field
Select	NativeSelect
AlertDialog	AlertDialog（复合组件，见下文）

Modal 是最常见的重命名 — 每个 <Modal>、<ModalOverlay>、 <ModalContent>、<ModalHeader>、<ModalBody>、<ModalFooter> 和 <ModalCloseButton> 都会变成 Dialog.* 复合组件的一部分：

// v2
<Modal isOpen={open} onClose={onClose}>
  <ModalOverlay />
  <ModalContent>
    <ModalHeader>Title</ModalHeader>
    <ModalBody>Body</ModalBody>
    <ModalFooter><Button onClick={onClose}>Close</Button></ModalFooter>
  </ModalContent>
</Modal>

// v3
<Dialog.Root open={open} onOpenChange={({ open }) => setOpen(open)}>
  <Dialog.Backdrop />
  <Dialog.Positioner>
    <Dialog.Content>
      <Dialog.Header><Dialog.Title>Title</Dialog.Title></Dialog.Header>
      <Dialog.Body>Body</Dialog.Body>
      <Dialog.Footer><Button onClick={() => setOpen(false)}>Close</Button></Dialog.Footer>
      <Dialog.CloseTrigger />
    </Dialog.Content>
  </Dialog.Positioner>
</Dialog.Root>

复合组件重写

v3 采用了一致的复合组件 API。codemod 会处理其中许多情况，但复杂的自定义用法 需要手动检查。

Checkbox

// v2
<Checkbox isChecked={val} onChange={fn}>Label</Checkbox>

// v3
<Checkbox.Root checked={val} onCheckedChange={fn}>
  <Checkbox.Control><Checkbox.Indicator /></Checkbox.Control>
  <Checkbox.Label>Label</Checkbox.Label>
</Checkbox.Root>

Progress

// v2
<Progress value={60} colorScheme="blue" />

// v3
<Progress.Root value={60} colorPalette="blue">
  <Progress.Track><Progress.Range /></Progress.Track>
</Progress.Root>

Accordion

// v2
<Accordion><AccordionItem><AccordionButton /><AccordionPanel /></AccordionItem></Accordion>

// v3
<Accordion.Root>
  <Accordion.Item value="item-1">
    <Accordion.ItemTrigger />
    <Accordion.ItemContent />
  </Accordion.Item>
</Accordion.Root>

FormControl → Field

// v2
<FormControl isInvalid={!!error} isRequired>
  <FormLabel>Email</FormLabel>
  <Input type="email" />
  <FormErrorMessage>{error}</FormErrorMessage>
  <FormHelperText>We'll never share your email.</FormHelperText>
</FormControl>

// v3
<Field.Root invalid={!!error} required>
  <Field.Label>Email</Field.Label>
  <Input type="email" />
  <Field.ErrorText>{error}</Field.ErrorText>
  <Field.HelpText>We'll never share your email.</Field.HelpText>
</Field.Root>

所有 FormControl 子部分都映射到 Field.*：

• FormLabel → Field.Label
• FormErrorMessage → Field.ErrorText
• FormHelperText → Field.HelpText
• FormControl 的 props isInvalid、isRequired、isDisabled → invalid、 required、disabled

Dialog / Drawer / Menu / Tabs 遵循相同的复合模式：使用 ComponentName.Root、.Trigger、.Content、.Item 等。请查阅 Chakra UI v3 文档了解每个组件的具体复合 API。

Next.js Image 和 Link（替代 @chakra-ui/next-js）

// v2 — @chakra-ui/next-js
import { LinkOverlay } from "@chakra-ui/next-js"

// v3 — asChild pattern
import NextLink from "next/link"
<ChakraLink asChild><NextLink href="/about">About</NextLink></ChakraLink>

import NextImage from "next/image"
<ChakraImage asChild><NextImage src="..." alt="..." /></ChakraImage>

---

第 8 步 — 主题迁移

styleConfig 和 multiStyleConfig → recipes

// v3 — single component (recipe)
import { defineRecipe } from "@chakra-ui/react"

// v2
const buttonStyle = {
  baseStyle: { fontWeight: "bold" },
  variants: { solid: { bg: "blue.500" } },
  defaultProps: { variant: "solid" },
}

const buttonRecipe = defineRecipe({
  base: { fontWeight: "bold" },
  variants: { variant: { solid: { bg: "blue.500" } } },
  defaultVariants: { variant: "solid" },
})

// v3 — slot recipe
import { defineSlotRecipe } from "@chakra-ui/react"

// v2 — multiStyleConfig (multi-part component)
const cardStyle = multiStyleConfig({
  parts: ["root", "header"],
  baseStyle: { root: { bg: "white" }, header: { fontWeight: "bold" } },
})

const cardSlotRecipe = defineSlotRecipe({
  slots: ["root", "header"],
  base: { root: { bg: "white" }, header: { fontWeight: "bold" } },
})

自定义 token 的类型生成

添加自定义 token、语义 token、recipe 或 slot recipe 后，运行 类型生成以保持 TypeScript 类型同步：

npx @chakra-ui/cli typegen ./theme.ts

复杂的主题迁移 — 如果你要迁移一个包含许多自定义 token、语义 token 或 多部分组件样式的大型 v2 主题，请使用 chakra-ui-theming 技能。它深入涵盖了 完整的 token/recipe/slot-recipe API，是比本节更好的指南。

---

第 9 步 — Next.js 特定事项

App Router

• 将 <Provider> 放在 app/layout.tsx 中（服务端组件 — 不要加 "use client"）
• 生成的 components/ui/provider.tsx 已经包含 "use client"
• 为 <html> 添加 suppressHydrationWarning 以防止颜色模式闪烁
• 不要将整个应用或布局包裹在 "use client" 中

Pages Router

// pages/_app.js
import { Provider } from "@/components/ui/provider"

export default function App({ Component, pageProps }) {
  return (
    <Provider>
      <Component {...pageProps} />
    </Provider>
  )
}

从 pages/_document.tsx 中移除任何 ColorModeScript — 它在 v3 中不再使用。

---

第 10 步 — 验证清单

迁移完成后逐一完成以下事项：

• 重新安装依赖：npm install / pnpm install
• TypeScript：npx tsc --noEmit — 解决所有类型错误
• Lint：npm run lint
• 构建：npm run build
• 目视验证颜色模式切换（浅色 ↔ 深色）
• 测试交互式组件：Dialog、Drawer、Menu、Tabs、Accordion
• 测试表单组件：Checkbox、Select/NativeSelect、Input、Radio
• 检查关键页面是否存在视觉回归
• 在代码库中搜索残留的 v2 导入：

  grep -r "ColorModeScript\|useColorModeValue\|extendTheme\|styleConfig\|@chakra-ui/icons\|@chakra-ui/next-js" src/
  

---

澄清问题（当上下文不明确时）

如果用户的版本、框架或范围不明确，请询问：

1. "你当前使用的是哪个版本的 @chakra-ui/react？"
2. "你使用的是 Next.js App Router、Pages Router、Vite 还是纯 React？"
3. "你是迁移整个代码库还是只迁移特定组件？"

如果在未询问的情况下继续，请清楚说明你的假设。