🛠️ Ant Design v4 → v6 迁移工具使用指南

本工具包包含 3 个辅助脚本和 1 个详细检查清单，帮助你高效完成迁移工作。

📦 工具包内容

migration-tools/
├── migration-checklist.md    # 📋 迁移检查清单（主文档）
├── scan-api-diff.js          # 🔍 API 差异扫描器
├── import-replace.js         # 🔧 批量替换工具
├── component-template.js     # 📝 组件模板生成器
└── USAGE.md                  # 📖 本使用指南

🚀 快速开始

Step 1: 扫描旧项目代码

先了解你的代码中有哪些需要修改的地方：

# 扫描旧项目代码，生成报告
node scan-api-diff.js /path/to/old-project/src

# 导出详细的 JSON 报告（可选）
node scan-api-diff.js /path/to/old-project/src --json=scan-report.json

输出示例：

📊 Ant Design v4 → v6 API 差异扫描报告
===============================================================================

📁 扫描统计:
   总文件数: 581
   已扫描: 581
   有问题的文件: 127

🚨 问题统计:
   🔴 Critical: 5 个
   🟠 High: 43 个
   🟡 Medium: 89 个
   🟢 Low: 12 个

📋 详细问题列表:
   ...

Step 2: 批量替换简单的 API

对于可以自动替换的 API（如 visible → open），使用批量替换工具：

# 预览将要修改的内容（强烈推荐先预览）
node import-replace.js /path/to/new-project/src --dry-run

# 确认无误后，执行替换并备份
node import-replace.js /path/to/new-project/src --backup

# 如果你很确定，可以直接替换（不推荐）
node import-replace.js /path/to/new-project/src

该工具会自动处理：

✅ visible → open
✅ onVisibleChange → onOpenChange
✅ moment → dayjs
✅ overlay → menu (Dropdown)
✅ BackTop → FloatButton.BackTop

Step 3: 生成新组件模板

在新项目中创建符合 v6 规范的组件：

# 生成基础组件
node component-template.js basic UserCard ./src/components/user

# 生成表单组件
node component-template.js form UserForm ./src/components/user

# 生成 ProTable 组件
node component-template.js proTable UserList ./src/components/user

# 生成完整的主题系统（重要！）
node component-template.js --theme ./src/theme

Step 4: 按照检查清单逐步迁移

打开 migration-checklist.md，按照清单逐个完成迁移任务。

🔍 工具 1: scan-api-diff.js - API 差异扫描器

功能

扫描代码中使用的 antd v4 API，标记需要修改的地方。

使用场景

✅ 开始迁移前，了解代码中有多少需要修改的地方
✅ 评估迁移工作量
✅ 识别高风险组件
✅ 迁移过程中，验证是否有遗漏

命令详解

# 基础用法
node scan-api-diff.js <目标目录>

# 导出 JSON 报告
node scan-api-diff.js <目标目录> --json=<输出文件.json>

实战示例

# 示例 1: 扫描整个 src 目录
node scan-api-diff.js ../old-project/src

# 示例 2: 只扫描特定模块
node scan-api-diff.js ../old-project/src/components/general

# 示例 3: 导出报告后用其他工具分析
node scan-api-diff.js ../old-project/src --json=report.json
cat report.json | jq '.issues | length'  # 统计问题数量

报告解读

报告会按严重程度分类问题：

🔴 Critical - 必须立即修改，否则代码无法运行
- 例如：使用了已废弃的 getFieldDecorator
🟠 High - 高优先级，会导致功能异常
- 例如：visible 属性不再生效
🟡 Medium - 中优先级，可能导致警告或不推荐的用法
- 例如：直接调用 message.success() 需要包裹 <App>
🟢 Low - 低优先级，建议优化
- 例如：BackTop 组件有更好的替代方案

输出文件

如果使用 --json 参数，会生成 JSON 格式的详细报告：

{
  "timestamp": "2026-02-14T10:30:00.000Z",
  "stats": {
    "totalFiles": 581,
    "scannedFiles": 581,
    "filesWithIssues": 127,
    "issues": {
      "critical": 5,
      "high": 43,
      "medium": 89,
      "low": 12
    }
  },
  "issues": {
    "src/components/general/ThemeSelect.tsx": [
      {
        "line": 42,
        "column": 8,
        "code": "visible={true}",
        "suggestion": "❌ 使用了 visible 属性",
        "fix": "将 visible 改为 open",
        "severity": "high",
        "component": "Modal/Drawer/Popover/Tooltip/Dropdown"
      }
    ]
  }
}

🔧 工具 2: import-replace.js - 批量替换工具

功能

自动替换代码中的 antd v4 API 调用。

使用场景

✅ 批量替换简单的 API 变更（如 visible → open）
✅ 替换 moment.js 为 dayjs
✅ 更新其他机械性的代码修改

⚠️ 重要警告

该工具会直接修改你的代码文件！

请务必：

先使用 --dry-run 预览
使用 --backup 备份原文件
使用 Git 等版本控制系统
在测试分支上操作

命令详解

# 预览模式（强烈推荐先运行）
node import-replace.js <目标目录> --dry-run

# 执行替换并备份
node import-replace.js <目标目录> --backup

# 直接替换（谨慎使用）
node import-replace.js <目标目录>

实战示例

# 示例 1: 先预览整个项目的修改
node import-replace.js ./src --dry-run

# 示例 2: 确认无误后执行替换，并备份原文件
node import-replace.js ./src --backup

# 示例 3: 只处理特定目录
node import-replace.js ./src/components/general --backup

# 示例 4: 查看备份文件
find ./src -name "*.bak" | head -5

# 示例 5: 如果替换有问题，恢复备份
find ./src -name "*.bak" -exec bash -c 'mv "$0" "${0%.bak}"' {} \;

替换规则

目前支持以下自动替换：

v4 API	v6 API	说明
`visible={...}`	`open={...}`	Modal/Drawer/Popover 等
`onVisibleChange={...}`	`onOpenChange={...}`	同上
`import moment from 'moment'`	`import dayjs from 'dayjs'`	DatePicker 相关
`moment(...)`	`dayjs(...)`	日期处理函数
`overlay={...}`	`menu={...}`	Dropdown 组件
`<BackTop>`	`<FloatButton.BackTop>`	返回顶部组件

注意事项

⚠️ 以下情况需要手动处理：

Dropdown 的 menu 属性
- 自动替换后，menu 需要返回 Menu 组件
- 可能需要调整代码结构
message/notification 静态方法
- 不会自动替换（因为需要包裹 <App> 组件）
- 建议迁移到 App.useApp() hook
Modal.confirm 等静态方法
- 同上，需要使用 Modal.useModal() hook
PageHeader 组件
- 已从 antd 移除
- 需要手动迁移到 @ant-design/pro-components

📝 工具 3: component-template.js - 组件模板生成器

功能

生成符合 v6 最佳实践的组件模板代码。

使用场景

✅ 创建新组件时，使用标准模板
✅ 重写旧组件时，参考最佳实践
✅ 生成主题系统文件

可用模板类型

类型	说明	适用场景
`basic`	基础组件	简单的展示组件
`form`	表单组件	包含表单验证、提交逻辑
`modal`	Modal 组件	弹窗组件
`table`	Table 组件	列表展示、分页
`proTable`	ProTable 组件	复杂的表格，带搜索、筛选

命令详解

# 生成组件
node component-template.js <类型> <组件名> [输出目录]

# 生成主题系统文件（特殊命令）
node component-template.js --theme [输出目录]

# 查看帮助
node component-template.js --help

实战示例

# 示例 1: 生成基础组件
node component-template.js basic UserCard ./src/components/user
# 输出: ./src/components/user/UserCard.tsx

# 示例 2: 生成表单组件
node component-template.js form UserForm ./src/components/user
# 输出: ./src/components/user/UserForm.tsx

# 示例 3: 生成 ProTable 组件
node component-template.js proTable UserList ./src/components/user
# 输出: ./src/components/user/UserList.tsx

# 示例 4: 生成主题系统（重要！）
node component-template.js --theme ./src/theme
# 输出:
#   ./src/theme/ThemeSwitch.tsx   (主题切换器)
#   ./src/theme/AppProvider.tsx   (App 提供者)
#   ./src/theme/tokens.ts         (Design Token 配置)

主题系统文件说明

使用 --theme 命令会生成完整的主题系统：

1. ThemeSwitch.tsx - 主题切换器

// 用法示例
import ThemeSwitch from './theme/ThemeSwitch';

<ThemeSwitch onChange={(mode) => {
  console.log('当前主题:', mode); // 'light' | 'dark'
}} />

功能：

✅ 亮色/暗黑主题切换
✅ 本地存储主题偏好
✅ 带图标和文字提示

2. AppProvider.tsx - 全局配置提供者

// 在根组件使用
import AppProvider from './theme/AppProvider';

function Root() {
  return (
    <AppProvider>
      <YourApp />
    </AppProvider>
  );
}

功能：

✅ 提供 ConfigProvider 配置
✅ 管理主题切换
✅ 提供全局 message/modal/notification

3. tokens.ts - Design Token 配置

// 自定义主题 Token
export const lightTheme = {
  token: {
    colorPrimary: '#1890ff',
    borderRadius: 6,
    // ...
  },
  components: {
    Button: {
      controlHeight: 32,
    },
  },
};

📋 工具 4: migration-checklist.md - 迁移检查清单

功能

详细的分阶段迁移任务清单。

使用方法

在你喜欢的 Markdown 编辑器中打开
按照 Phase 顺序完成任务
完成一项勾选一项 [ ] → [x]
记录遇到的问题和解决方案

文档结构

📊 迁移进度总览
└── 总体进度追踪

🎯 Phase 1: 基础设施层
└── 类型定义、Redux、路由

🎯 Phase 2: 通用组件层 ⭐ 当前优先级
└── general、auth、api

🎯 Phase 3: 业务组件层
└── 按模块逐个迁移

🎯 Phase 4: 样式和主题系统 ⚠️ 重大变更
└── CSS → Design Token

🎯 Phase 5: 测试和优化
└── 功能测试、性能优化

📚 关键 API 变更速查表
└── 常用组件对照表

🔧 常见问题和解决方案
└── 错误处理指南

🎯 推荐工作流程

方案 1: 稳妥型（推荐给大型项目）

# Step 1: 扫描旧项目，评估工作量
node scan-api-diff.js ../old-project/src --json=scan-report.json

# Step 2: 生成主题系统文件
node component-template.js --theme ./src/theme

# Step 3: 配置根组件使用 AppProvider
# (手动修改 src/index.tsx)

# Step 4: 选择一个简单模块开始迁移（如 general）
# 方式 A: 手动迁移（更安全）
cp -r ../old-project/src/components/general ./src/components/

# 方式 B: 复制后使用替换工具
node import-replace.js ./src/components/general --backup

# Step 5: 测试该模块是否正常工作

# Step 6: 重复 Step 4-5，逐个模块迁移

# Step 7: 最后扫描一次，确保没有遗漏
node scan-api-diff.js ./src

方案 2: 快速型（推荐给小型项目）

# Step 1: 直接复制所有代码到新项目
cp -r ../old-project/src/* ./src/

# Step 2: 批量替换简单的 API
node import-replace.js ./src --dry-run  # 先预览
node import-replace.js ./src --backup   # 执行替换

# Step 3: 生成主题系统
node component-template.js --theme ./src/theme

# Step 4: 扫描剩余问题
node scan-api-diff.js ./src

# Step 5: 根据报告手动修复剩余问题

# Step 6: 测试所有功能

🔥 常见问题 FAQ

Q1: 替换工具会破坏我的代码吗？

A: 可能会。所以：

✅ 务必先用 --dry-run 预览
✅ 使用 --backup 备份
✅ 使用 Git 等版本控制
✅ 先在小范围测试

Q2: 扫描器报告太多问题怎么办？

A: 分优先级处理：

先处理 🔴 Critical 和 🟠 High
🟡 Medium 可以逐步处理
🟢 Low 可以最后优化

Q3: 某些 API 无法自动替换怎么办？

A: 手动处理：

参考 migration-checklist.md 中的 API 对照表
查看生成的组件模板作为参考
查阅 Ant Design 官方文档

Q4: 主题系统应该如何集成？

A: 三步走：

# 1. 生成主题文件
node component-template.js --theme ./src/theme

# 2. 在根组件引入
import AppProvider from './theme/AppProvider';

# 3. 包裹你的 App
<AppProvider>
  <App />
</AppProvider>

Q5: ProTable/ProForm 如何迁移？

ProComponents 也有版本升级
使用 component-template.js proTable 生成新模板
对比新旧代码，逐步调整

Q6: 样式突然失效怎么办？

A: 检查：

✅ 是否有覆盖 antd 默认样式的 CSS
✅ 类名是否发生变化
✅ 是否需要改用 Design Token
✅ 是否需要使用 classNames API

Q7: 扫描器漏报或误报怎么办？

扫描器基于正则匹配，可能有遗漏
建议结合人工检查
可以修改 scan-api-diff.js 添加新规则

📚 参考资源

官方文档

工具资源

💡 最佳实践建议

1. 分阶段迁移

不要一次性迁移所有代码，按模块逐个迁移并测试。

2. 保持两个版本

在迁移期间，保持 v4 版本可运行，方便对比。

3. 及时记录

在 migration-checklist.md 中记录遇到的问题和解决方案。

4. 代码审查

迁移后的代码要经过审查，确保符合 v6 最佳实践。

5. 性能监控

迁移前后对比性能指标，确保没有性能退化。

6. 增量发布

如果是生产项目，建议采用灰度发布策略。

🎉 完成检查清单

当你完成迁移后，检查以下项目：

所有 TypeScript 编译错误已修复
所有页面可以正常访问
核心功能测试通过
主题切换正常工作
国际化正常工作
移动端响应式正常
性能没有明显下降
控制台无报错和警告
代码已提交到 Git
团队成员已了解新特性

祝你迁移顺利！🚀

如有问题，请参考 migration-checklist.md 或查阅官方文档。

USAGE.md 14 KB 永久連結 文件歷史 原始文件

🛠️ Ant Design v4 → v6 迁移工具使用指南

📦 工具包内容

🚀 快速开始

Step 1: 扫描旧项目代码

Step 2: 批量替换简单的 API

Step 3: 生成新组件模板

Step 4: 按照检查清单逐步迁移

🔍 工具 1: scan-api-diff.js - API 差异扫描器

功能

使用场景

命令详解

实战示例

报告解读

输出文件

🔧 工具 2: import-replace.js - 批量替换工具

功能

使用场景

⚠️ 重要警告

命令详解

实战示例

替换规则

注意事项

📝 工具 3: component-template.js - 组件模板生成器

功能

使用场景

可用模板类型

命令详解

实战示例

主题系统文件说明

1. ThemeSwitch.tsx - 主题切换器

2. AppProvider.tsx - 全局配置提供者

3. tokens.ts - Design Token 配置

📋 工具 4: migration-checklist.md - 迁移检查清单

功能

使用方法

文档结构

🎯 推荐工作流程

方案 1: 稳妥型（推荐给大型项目）

方案 2: 快速型（推荐给小型项目）

🔥 常见问题 FAQ

Q1: 替换工具会破坏我的代码吗？

Q2: 扫描器报告太多问题怎么办？

Q3: 某些 API 无法自动替换怎么办？

Q4: 主题系统应该如何集成？

Q5: ProTable/ProForm 如何迁移？

Q6: 样式突然失效怎么办？

Q7: 扫描器漏报或误报怎么办？

📚 参考资源

官方文档

工具资源

💡 最佳实践建议

1. 分阶段迁移

2. 保持两个版本

3. 及时记录

4. 代码审查

5. 性能监控

6. 增量发布

🎉 完成检查清单

USAGE.md 14 KB

永久連結文件歷史原始文件