refine 项目 Ant Design v4 到 v5 迁移实战指南CSS-in-JS 升级、Codemod 自动化与手动迁移要点【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine本篇迁移指南面向使用pankod/refine-antd3.x.x基于 antd 4.x的项目系统讲解如何升级到pankod/refine-antd4.x.x基于 antd 5.x。你将掌握通过 refine CLI 或 Codemod 自动迁移的完整流程理解 antd 5 从less转向 CSS-in-JS 的底层原理并学会处理自定义Sider、自定义Header、.less样式文件等无法自动迁移场景的手动改造方案同时了解升级后常见编译错误的排查与修复。升级背景antd 5 带来了什么变化Ant Design 发布了新的主版本 v5refine 的 Ant Design UI 包也随之跟进。本次升级的核心变化来自 antd 5 本身less被移除全面采用 CSS-in-JSantd 5 放弃了基于less的样式方案改为 CSS-in-JS底层使用ant-design/cssinjs作为运行时解决方案以便更好地支持动态主题。部分组件被移除或重命名部分 API 发生变更例如PageHeader组件被移入ant-design/pro-componentsComment组件被移入ant-design/compatible。moment.js被替换为day.jsantd 5 默认使用体积更小的day.js处理日期逻辑。less从antd包中移除项目中原有的less相关配置与样式文件需要迁移。对 refine 的直接影响refine在List、Create、Edit、Show组件内部使用PageHeader并已将其作为依赖引入。这意味着升级到pankod/refine-antd4.x.x后你不需要手动安装ant-design/pro-components包——refine 已经替你处理了。在当前仓库的 antd 包源码中可以看到List、Create、Edit、Show的 CRUD 组件目录结构依然保留且包依赖声明中确实直接依赖了ant-design/pro-layout、antd、dayjs等运行时依赖与文档描述一致。版本对应关系升级前请先确认你的版本处于下表中的对应关系refine包Ant Design 版本pankod/refine-antd3.x.xantd4.x.xpankod/refine-antd4.x.xantd5.x.x关于 antd 4 到 5 的完整变更明细请以 Ant Design 官方迁移指南为准。更新包两种方式任选其一方式一使用 refine CLI推荐如果你已经在项目中接入 refine CLI可以直接使用update命令批量更新 refine 相关包npm run refine update该命令会自动检测并升级项目内的 refine 依赖。若项目中还没有 refine CLI可以参考仓库中的 CLI 实现位于 packages/cli将其引入现有项目后再执行。方式二手动安装直接安装最新版pankod/refine-antdnpm i pankod/refine-antdlatest安装后请检查package.json中pankod/refine-antd的版本号是否落在4.x.x区间内。使用 Codemod 自动迁移强烈推荐pankod/refine-codemod包可以自动处理大部分破坏性变更将你的pankod/refine-antd从 3.x.x 迁移到 4.x.x无需手动修改代码。进入项目根目录即包含package.json的目录执行npx pankod/refine-codemod antd4-to-antd5执行完成后你的项目即升级为pankod/refine-antd4.x.x。⚠️ 注意自定义或 swizzled 过的组件如自定义的 Sider以及.less 文件无法被自动迁移需要你手动处理。Codemod 背后做了什么在当前仓库的 Codemod 入口中antd4-to-antd5被注册为官方 transform 之一。其实际转换逻辑位于 antd4-to-antd5 转换器主要完成两类替换样式导入替换updateStyles将pankod/refine-antd/dist/styles.min.css的导入替换为pankod/refine-antd/dist/reset.css。组件 Props 重命名updateActionButtonsPropstoHeaderButtons针对Show、Edit、List、Create四个组件将actionButtons替换为headerButtons、pageHeaderProps替换为headerProps。另外值得一提的是在从 refine 3 升级到 refine 4 时refine3-to-refine4Codemod 会先检查你的项目是否仍在使用 antd 4即pankod/refine-antd是否处于 3.x如果是会提示你先完成本指南描述的 antd 升级再继续 refine 主版本升级——这也说明 antd 5 迁移是 refine 4 升级链路上的前置步骤。Codemod 默认只转换tsx,ts,jsx,js扩展名文件并会忽略node_modules、build、.next、dist、.cache等目录同时提供--force、--dry、--print等选项见 CLI 帮助信息执行前还会检查 Git 工作区是否干净避免覆盖未提交的改动。手动迁移步骤如果不使用 Codemod或 Codemod 无法覆盖自定义部分可以按以下步骤手动迁移。更新导入从styles.min.css到reset.cssantd 5 不再随包提供 CSS 文件CSS-in-JS 支持按需加载样式因此原先的styles/antd.less也被弃用。如果你需要重置一些基础样式请改导入pankod/refine-antd/dist/reset.css- import pankod/refine-antd/dist/styles.min.css; import pankod/refine-antd/dist/reset.css;在当前仓库的 antd 包中./dist/reset.css被显式声明为可导出入口且源码中的 reset.css 正是随包发布的基础样式重置文件。更新 PropsactionButtons/pageHeaderProps→headerButtons/headerPropsactionButtons和pageHeaderProps这两个 props 在pankod/refine-antd3.x.x中已被标记为弃用并在pankod/refine-antd4.x.x中从List、Create、Edit、Show组件中移除原因是与所有 UI 包的 prop 命名保持一致。请改用headerButtons和headerProps- List actionButtons{actionButtons} pageHeaderProps{pageHeaderProps} List headerButtons{actionButtons} headerProps{pageHeaderProps}- 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}以List为例在当前仓库的源码中可以看到headerButtons和headerProps已经是正式生效的 propsheaderButtons支持传入 React 节点或一个接收createButtonProps等参数的回调函数最终渲染在页面头部区域headerProps则会被透传给底层的 PageHeader 组件。对应的测试用例如 list/index.spec.tsx也以headerButtons回调形式编写可作为迁移后的写法参考。自定义Sider的颜色适配如果你自定义或 swizzled 过Sider组件升级后可能出现颜色不匹配的问题。解决办法是给Sider中的Menu组件指定深色主题AntdLayout.Sider collapsible collapsed{collapsed} onCollapse{(collapsed: boolean): void setCollapsed(collapsed)} collapsedWidth{isMobile ? 0 : 80} breakpointlg style{isMobile ? antLayoutSiderMobile : antLayoutSider} RenderToTitle collapsed{collapsed} / Menu themedark selectedKeys{[selectedKey]} defaultOpenKeys{defaultOpenKeys} modeinline onClick{() { if (!breakpoint.lg) { setCollapsed(true) } }} {renderSider()} /Menu /AntdLayout.Sider自定义Header的颜色适配同样的如果你自定义或 swizzled 过Header组件也可能出现颜色不匹配问题。antd 5 的主题由 CSS-in-JS 动态计算硬编码的背景色会与新的主题机制冲突因此建议移除Header中固定的背景色AntdLayout.Header style{{ display: flex, justifyContent: flex-end, alignItems: center, padding: 0px 24px, height: 64px, - backgroundColor: #FFF, }}移除后Header 的背景色会跟随 antd 5 的 token 主题体系自动适配避免亮色/暗色切换时的色差问题。LESS 用户Ant Design 移除了less改为使用并推荐CSS-in-JS。如果你项目中存在.less样式文件需要手动迁移到 CSS-in-JS。迁移要点包括将基于less变量如primary-color的样式改写为使用 antd 5 的 theme tokenConfigProvider的theme配置将嵌套选择器、等 less 语法改写为标准 CSS 或 CSS-in-JS 对象写法移除对less-loader、less编译器以及babel-plugin-import等 less 相关构建配置的依赖。具体迁移细节可参考 Ant Design 官方文档中的 less 迁移章节。已知问题升级后的编译错误部分用户在从pankod/refine-antd3.x.x升级到pankod/refine-antd4.x.x后报告了编译错误相关讨论见 issue#1 与 issue#2并提供了两种解决方案。解决方案一彻底重装依赖如果编译错误源于依赖树不干净或缓存残留可以按顺序执行删除node_modules文件夹删除package-lock.json文件重新执行npm install解决方案二升级 React 相关包某些编译错误与 React 版本不匹配有关将 React 及其 DOM 绑定升级到最新版本即可解决npm install reactlatest react-domlatest迁移后的验证建议完成迁移后建议从以下几点进行验证运行项目开发服务器确认页面正常渲染控制台无styles.min.css相关的资源加载 404检查List、Create、Edit、Show页面头部按钮与标题布局是否符合预期对应headerButtons/headerProps的渲染效果切换 antd 5 的亮/暗主题通过ConfigProvider的theme确认自定义Sider、自定义Header不再出现背景色不协调执行npm run build或项目的生产构建命令确认没有因less依赖缺失导致的编译失败如果你准备继续升级 refine 主版本如refine3-to-refine4此时 antd 5 迁移已完成Codemod 的版本检查即可顺利通过。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考