Refine 项目升级 Ant Design 时如何按迁移指南处理组件与 API 变化？-编程实验室

Refine 项目升级 Ant Design 时如何按迁移指南处理组件与 API 变化？

【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards & B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine

如果你的 Refine 管理后台基于 Ant Design（antd）4.x 开发，现在需要升级到 antd 5.x，就要处理这一大版本带来的破坏性变化：antd 移除了less改用CSS-in-JS（底层依赖@ant-design/cssinjs）、部分组件被移除或改名、部分 API 发生变化。Refine 的 Ant Design Migration Guide 给出了完整的升级路径：先更新@refinedev/antd包，再用@refinedev/codemod自动迁移或手动修改代码。本文按该指南梳理从版本对应关系到逐项代码修改、再到编译错误处理的全过程。

升级前的版本对应关系

指南中明确了一份 Refine 包与 antd 版本的对应表，升级前先确认自己当前处于哪一行：

Refine 包	Ant Design 版本
`@pankod/refine-antd@3.x.x`	`antd@4.x.x`
`@pankod/refine-antd@4.x.x`、`@refinedev/antd@5.x.x`	`antd@5.x.x`

升级主路径是把@refinedev/antd从 3.x.x 升到 4.x.x，配套的 antd 从 4.x 升到 5.x。

更新 @refinedev/antd 到 4.x

指南要求将@refinedev/antd更新到4.x.x，提供两种途径：

方式一：Refine CLI（前提：项目已配置 Refine CLI）

npm run refine update

这是交互式命令，运行后会列出可更新的 Refine 包，按 Patch / Minor / Major Updates 分组展示「从哪个版本到哪个版本」。例如 CLI 文档中的示例输出：

> npm run refine update ? Choose packages to update (Press <space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed) Package From To Patch Updates ◯ @refinedev/cli 1.5.1 -> 1.5.3 Minor Updates ◯ @refinedev/airtable 2.1.1 -> 2.7.8 ◉ @refinedev/core 3.88.1 -> 3.90.4 ... Major Updates ◯ @refinedev/airtable 2.1.1 -> 3.33.0 ◯ @refinedev/simple-rest 2.6.0 -> 3.35.2

（以上为文档示例。）跳过交互模式可用--all标志把所有过期的 Refine 包更新到所选 tag。项目还没接入 CLI 时，先按 CLI 文档中“how to add to an existing project”一节配置。

方式二：手动安装

npm i @refinedev/antd@latest

用 Codemod 自动迁移（指南推荐）

@refinedev/codemod会解析项目代码并自动处理破坏性变化，把@refinedev/antd从 3.x.x 迁移到 4.x.x，无需手动步骤。对应的迁移器在 codemod 包中名为antd4-to-antd5: Transform from antd 4.x.x to at least 5.x.x（见 packages/codemod/src/index.ts）。

进入项目根目录（即package.json所在目录）执行：

npx @refinedev/codemod antd4-to-antd5

指南给出的成功判定就是：命令执行完即完成，此时项目已使用@refinedev/antd@4.x.x。

注意一条限制：自定义（Customized）或 swizzled 的组件以及.less文件无法被自动迁移，需要按下面几节手动处理。查看 codemod 可用选项可以运行npx @refinedev/codemod --help（见 codemod 包 README）。

需要手动处理的组件与 API 变化

无论你用了 codemod，以下变化都建议逐项核对一遍。

1. CSS 导入方式变化

antd 5.x 不再在包内附带 CSS，原来的styles/antd.less也已废弃。CSS-in-JS 支持按需导入；如果还需要重置基础样式，改为导入@refinedev/antd/dist/reset.css：

- import "@refinedev/antd/dist/styles.min.css"; + import "@refinedev/antd/dist/reset.css";

2.`actionButtons`与`pageHeaderProps`被移除

这两个 props 在@refinedev/antd@3.x.x中已标记废弃，在@refinedev/antd@4.x.x中从<List>、<Create>、<Edit>、<Show>组件中彻底移除（原因是与其他 UI 包不一致）。请改用headerButtons和headerProps：

- <List actionButtons={actionButtons} pageHeaderProps={pageHeaderProps}> + <List headerButtons={actionButtons} headerProps={pageHeaderProps}>

<Create>、<Show>、<Edit>同理：

- <Create actionButtons={actionButtons} pageHeaderProps={pageHeaderProps}> + <Create headerButtons={actionButtons} headerProps={pageHeaderProps}>

- <Show actionButtons={actionButtons} pageHeaderProps={pageHeaderProps}> + <Show headerButtons={actionButtons} headerProps={pageHeaderProps}>

- <Edit actionButtons={actionButtons} pageHeaderProps={pageHeaderProps}> + <Edit headerButtons={actionButtons} headerProps={pageHeaderProps}>

此外指南还说明了几个组件层面的去向，升级后遇到相关引用时留意：

<PageHeader>移入@ant-design/pro-components。Refine 在<List>、<Create>、<Edit>、<Show>中使用了<PageHeader>并已将其加入依赖，无需手动安装@ant-design/pro-components；
<Comment>移入@ant-design/compatible；
moment.js被替换为day.js；
antd包移除了less。

更多细节以 Ant Design 官方的 antd 5 迁移文档为准（指南中引用了 Ant Design 自己的 migration-v5 文档）。

3. 自定义（swizzled）`<Sider>`：颜色不匹配

如果你自定义过<Sider>组件，升级后可能出现颜色不匹配。解决办法是给<Sider>内的<Menu>加上theme='dark'：

<AntdLayout.Sider collapsible collapsed={collapsed} onCollapse={(collapsed: boolean): void => setCollapsed(collapsed)} collapsedWidth={isMobile ? 0 : 80} breakpoint='lg' style={isMobile ? antLayoutSiderMobile : antLayoutSider}> <RenderToTitle collapsed={collapsed} /> <Menu + theme='dark' selectedKeys={[selectedKey]} defaultOpenKeys={defaultOpenKeys} mode='inline' onClick={() => { if (!breakpoint.lg) { setCollapsed(true) } }}> {renderSider()} </Menu> </AntdLayout.Sider>

4. 自定义（swizzled）`<Header>`：颜色不匹配

自定义过<Header>时同样可能出现颜色不匹配，处理方式是移除其中写死的背景色：

<AntdLayout.Header style={{ display: 'flex', justifyContent: 'flex-end', alignItems: 'center', padding: '0px 24px', height: '64px', - backgroundColor: '#FFF', }}>

5.`.less`文件用户：手动迁移到 CSS-in-JS

如果你在项目中写过.less样式，由于 antd 已移除less、推荐使用 CSS-in-JS，这些文件需要按 Ant Design 官方的 less 迁移说明手动改写，codemod 不会代做这一步。

升级后遇到编译错误怎么办

有用户报告从@refinedev/antd@3.x.x升到4.x.x后出现编译错误，指南收录了两个已验证的解决方案：

方案 1：删除node_modules文件夹和package-lock.json，然后重新npm install。

副作用说明：这一步会清掉项目当前的依赖安装结果和锁文件并完整重装依赖，只针对 npm 项目，执行前确认没有其他未提交的依赖改动。

方案 2：

npm install react@latest react-dom@latest

结果确认与参考资料

按指南流程走完后的判定依据是：

codemod 执行完成后，项目使用的就是@refinedev/antd@4.x.x（配合 antd 5.x）；
<List>等四个页面组件上不再使用actionButtons/pageHeaderProps，已切换为headerButtons/headerProps，否则在 4.x 下这些 props 已不存在；
自定义<Sider>/<Header>页面检查无颜色不匹配现象；
若编译失败，对照上文两个已知问题的解决方案处理。

Refine 项目升级 Ant Design 时如何按迁移指南处理组件与 API 变化？