📚 Ant Design 4 升级至 5：一份实用的参考变更指南 📝vite5 + react18 + antd4

本文记录了作者升级antd5过程中的遇到的问题，包含了官方升级文档中没有说明的一些地方，希望能帮助到大家避免重复踩坑

项目技术栈

vite5 + react18 + antd4 ERP项目

升级背景

2017年项目，当时项目使用的是webpack ant3 版本，我2022年接手，项目代码代码质量差，没有规范，组件代码复制粘贴多冗余高，项目配置混乱，目录混乱，屎山pro max版。期间升级了4.0，从webpack更换到vite3，修复了一系列问题，但是有些ant3的写法还残留着，项目问题仍然不少，借着升级antd5同时修复一些以前的代码问题，紧跟时代潮流，同时优化一下用户体验。

开始升级

按照官方文档提供的升级工具先跑一下。

npm install --save antd@5.x

没有使用到 PageHeader 的可以不安装 @ant-design/pro-components，可以先全局搜索一下

npm install --save @ant-design/compatible@v5-compatible-v4
npm install --save @ant-design/pro-components

运行官方工具升级

npx -p @ant-design/codemod-v5 antd5-codemod src

注意 codemod 不能涵盖所有场景，建议还是要按不兼容的变化逐条排查。

删除导入报错的样式需要全局搜索一下每个地方都要删掉，根据你自己项目的情况考虑要不要记录变动的地方，以方便后续检查

//--删除以下导入
import 'antd/dist/antd.css';
import 'antd/dist/reset.css';
@import (reference) '~antd/es/style/themes/index';
import '@ant-design/pro-table/dist/table.css // 如果使用

配置vite.config.js，antd 的 less 变量通过 less-loader 注入

// ++
import { convertLegacyToken, defaultTheme } from '@ant-design/compatible/lib'
const { defaultAlgorithm } = theme
const mapV5Token = defaultAlgorithm(defaultSeed)
const v5Vars = convertLegacyToken(mapV5Token)

// defineConfg 中++
css: {
  preprocessorOptions: {
    less: {
      javascriptEnabled: true,
      modifyVars: v5Vars
    },
    scss: {
      additionalData: '@import "src/static/style/var.scss";',
      modifyVars: v5Vars
    }
  }
},

项目入口index.js中,添加App组件包裹路由,同时要做一下浏览器的兼容性。官网文档是这么说的：实测了社区的一些方案，没有完美的解决办法。添加 <StyleProvider hashPriority="high" transformers={[legacyLogicalPropertiesTransformer]}> 去处理一下，在chromre 87内核版本一下最起码会展示出页面的样式，问题还有很多例如Space组件失效了，message组件也挂了，最起码不会变成事故。我的处理方案是在页面顶部提示用户浏览器版本低，建议升级。

import { ConfigProvider, App } from 'antd'

//...
root.render(
  <BrowserRouter>
    <ConfigProvider locale={zhCN}>
      <StyleProvider hashPriority="high" transformers={[legacyLogicalPropertiesTransformer]}>
        <App>
          <Routes>
           {/*...*/}
          </Routes>
        </App>
      </StyleProvider>
    </ConfigProvider>
  </BrowserRouter>
)

移除 PageHeader 组件，移至 @ant-design/pro-components 中维护。
@react-buddy/palette-antd 更新至 5 我项目中使用了这个工具也需要升级一下不然报错
如果顺利的话，项目没有报错可以启动了，一般可能还会有一些导入的问题。可以先修复 / 注释。先保证项目跑起来。后面就是根据antd的升级文档根据组件变更点逐一修改。

以下是我项目中antd 文档没有说明的一些问题。

ProTable 的样式还是4.0的样式
样式没有生效，proTable 版本还是3.x,升级安装到5.x版本即可解决
ProTable menu 配置项！
启用的proTable自带的tab切换的 type=='tab'，相关的item的tab字段都要变成label，不然tab直接不展示，真的很坑！
页面默认含有边距样式问题
历史重置样式文件样式冲突，删掉只保留App包裹。
优化以前冗余样式
历史的项目中预置的样式文件，无使用，查找用法安全删除。
替换主题颜色
有些样式是编写在行内style样式中，比如 #1890ff 改为 #1677ff
TreeSelect 、 select 组件
dropdownMatchSelectWidth 属性全部更名为 popupMatchSelectWidth
Select
border=false 改为 variant = 'borderless' 属性
showArrow=false 改为 suffixIcon={null}

Modal 、 Drawer、 Card 组件
bodystyle headerStyle xxxStyle xxxClassname 移除, 统一使用 classnames styles 支持传入header body mask footer content 对象
eg:


const classNames = {
  body: styles['my-modal-body'],
  mask: styles['my-modal-mask'],
  header: styles['my-modal-header'],
  footer: styles['my-modal-footer'],
  content: styles['my-modal-content'],
};

const modalStyles = {
  header: {
    borderLeft: `5px solid ${token.colorPrimary}`,
    borderRadius: 0,
    paddingInlineStart: 5,
  },
  body: {
    boxShadow: 'inset 0 0 5px #999',
    borderRadius: 5,
  },
  mask: {
    backdropFilter: 'blur(10px)',
  },
  footer: {
    borderTop: '1px solid #333',
  },
  content: {
    boxShadow: '0 0 30px #999',
  },
};

Calendar 组件 dateFullCellRender 、dateCellRender、monthFullCellRender 、monthCellRender 移动到cellRender 中判断 info.type 使用
message.warn 现在被彻底移除，请使用 message.warning 代替
moment 替换 dayjs 参考升级文档，建议全局替换注意检查moment的一些功能是否需要导入dayjs的扩展使用
eg：
```
  import duration from 'dayjs/plugin/duration'
  dayjs.extend(duration)
```
@ant-design/compatible 导入问题修复移除老的Form组件和Icon组件

// 移除antd3写法
<Icon type='xx' />

antd3版本的form表单全部更换成5版本的写法
text-center样式对于Pagination不再生效

全部升级完了启动页面逐一排查，顺便把一些老页面的样式优化了一下。改了差不多五百多个文件，然后发布线上等死结束。

还有哪些坑，有小伙伴可以放在评论区。