react-admin 版本演进全解读：从 CHANGELOG 看 3.x 到 5.x 的核心变化、破坏性变更与升级实践

react-admin 版本演进全解读：从 CHANGELOG 看 3.x 到 5.x 的核心变化、破坏性变更与升级实践

【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址: https://gitcode.com/gh_mirrors/re/react-admin

本篇文章以仓库根目录的 CHANGELOG.md 为主线，系统梳理 react-admin 从 v3.9.0 到 v5.15.3 的完整演进脉络，重点拆解 v4、v5 两次大版本的架构级变化（数据获取、表单、路由、主题体系的替换），并给出 Webpack、Vite、Jest 等工程配置的升级实操指引。读完本文，你将掌握如何通过 CHANGELOG 定位某个组件、行为或依赖在哪个版本发生了变化，以及如何在升级时快速对照源码验证。

一、CHANGELOG 覆盖范围与版本矩阵

CHANGELOG.md是 react-admin 官方维护的唯一完整版本记录，按"版本号倒序 + 发布说明"的结构组织，覆盖自v3.9.0至v5.15.3（本文写作时仓库最新记录）的全部正式版本与 v5 的 alpha/beta/rc 预发布版本，全文约 3800 行。

• v3.x 分支（v3.9.0 ~ v3.19.11）：TypeScript 类型发布、<ReferenceField>/<ArrayInput>等核心组件持续迭代、引入遥测（telemetry）、局部支持mutationMode。
• v4.x 分支（v4.0.0 ~ v4.16.19）：架构全面现代化，移除 Redux，换装react-query、react-hook-form、react-router v6、MUI v5。
• v5.x 分支（v5.0.0 ~ v5.15.3）：支持 React 18/19、MUI v6/v7/v9、react-router v7、TanStack Router 适配，新增DataTable、离线支持、访问控制（Access Control）等。

从仓库根目录的 package.json 可以看到，本项目是一个典型的lerna + yarn workspaces monorepo，核心源码分散在packages/ra-core（无头逻辑）、packages/ra-ui-materialui（MUI 组件层）、packages/react-admin（对外聚合包）等目录中，CHANGELOG 中的绝大多数条目都能在这些包中找到对应实现。

二、v5.0.0：一次面向体验与工程效率的大版本

v5.0.0 的发布说明在 CHANGELOG 中占据极长篇幅，官方将其定义为"新特性 + 破坏性变更"双重属性的版本，主要分为以下几大主题。

2.1 UI 体验改进

• 应用默认自带主题切换器与暗色主题（此前需自行配置）。
• 所有Input 默认fullWidth，表单布局更统一。
• 链接默认带下划线，可点击性更清晰。
• 从 Edit/Create 视图返回时，列表页会恢复滚动位置。
• Layout 代码抛错时触发全局Error Boundary（新增<Error>兜底页）。
• Button 尺寸可通过 props 设置。

2.2 应用初始化与布局简化

• 自定义布局组件只需渲染 children，不再要求手动转发大量 props。
• Layout、AppBar、Menu 等不再层层注入 props，改用 Context。
• 新增useDefaultTitle()Hook，可在应用任意位置读取应用标题。

2.3 Data Provider 与列表页

• Data Provider 支持取消未挂载组件的查询（opt-in）。
• GraphQL 系 Data Provider 改为同步初始化（不再返回 Promise）；ra-data-graphql-simple新增 Sparse Fields、updateMany/deleteMany支持。
• withLifecycleCallbacks支持通配符与回调数组。
• <Datagrid rowClick>默认开启，按资源定义自动链接到 edit 或 show 视图。
• bulkActionButtons从<List>迁移为<Datagrid>的属性。
• setFilters默认不再防抖。

2.4 表单与输入体系

• Input 校验错误不再要求先 touched才显示。
• ReferenceInput默认使用recordRepresentation，更智能。
• 服务端校验更健壮；warnWhenUnsavedChanges恢复正常。
• 引入SourceContext，TranslatableInputs、ArrayInput、ReferenceManyInput等复合组件无需再通过cloneElement/FormDataConsumer.getSource层层透传 source。
• 所有 Input 拥有唯一 ID，消除重复 ID 警告。

2.5 工程依赖与 TypeScript

• 最低要求 React 18（以利用 Concurrent React），彻底放弃 IE。
• useGetOne等数据 Hook 的返回类型基于请求状态做智能类型收窄，强制开发者为错误分支做准备。
• PropTypes 全部移除，避免与 TypeScript 类型冲突。
• create-react-admin支持非交互模式；ra-data-fakerest支持delay参数模拟网络延迟。

官方对升级成本的估计是：约 5 万行代码的 react-admin 应用升级到 v5 大约需要 2 天。

三、v5.13：ESM 兼容与打包器配置更新（重点实操）

v5.13.0 是一个"看起来普通、实则影响所有下游构建"的版本，CHANGELOG 专门给出了三类配置更新，升级到该版本及之后的读者应当逐条核对。

3.1 react-hook-form 版本下限

本版本将最低要求的react-hook-form提升到7.65.0。如果你的package.json中该依赖版本较低，需要同步升级。

3.2 Jest 配置更新

由于 react-admin 的模块导出改为完全兼容 ESM（对应 PR #10995），如果你使用CJS 模式的 Jest（默认配置），需要更新 Jest 配置。仓库 jest.config.js 与测试基础设施（test-setup.js、test-global-setup.js）可作为对照参考。

3.3 Webpack 配置更新

如果你使用 MUI v5 或 MUI v6，需要为.m?js文件补充如下规则：

{ // Your config modules: { rules: [ // Your other rules { test: /\.m?js/, type: "javascript/auto", }, { test: /\.m?js/, resolve: { fullySpecified: false, }, }, ] } }

3.4 Vite 配置更新

如果使用 MUI v5，需要为@mui/icons-material增加 ESM 别名：

export default defineConfig(({ mode }) => ({ // Your config resolve: { // Your resolve config alias: [ // Your other aliases { find: /^@mui\/icons-material\/(.*)/, replacement: "@mui/icons-material/esm/$1", }, ] } });

从源码角度验证：v5.13 还重构了包的导出（见packages/react-admin/src/index.ts与packages/ra-core、packages/ra-ui-materialui的入口文件），这也是"包导出改进"（Improve packages exports）在 CHANGELOG 中多次出现的原因。

四、v4.0.0：现代化重构的里程碑

v4 的发布说明是理解 react-admin 内部架构的钥匙，它标志着框架从"Redux + saga + 自研数据获取"全面切换到现代 React 生态。

4.1 依赖层面的替换

• Redux / redux-saga / connected-react-router 全部移除，改为：
  • 数据获取：react-query（v5 中继续演进）
  • 表单：react-final-form替换为react-hook-form（initialValues改名defaultValues即源于此）
  • 路由：react-router v6（v5 中升级到 v7，并新增 TanStack Router 适配层）
  • 富文本：Quill 替换为 TipTap（<RichTextInput>）
  • UI：MUI v4 升级到MUI v5，支持sxprops
• React 18 兼容。

4.2 API 与语法层面的破坏性变更

• Record类型更名为RaRecord。
• 移除 prop 注入与 child cloning，全面改用 Context（RecordContext、ResourceContext、ChoicesContext等）。
• 移除basePath、addLabel、allowEmpty、undoableprop、useQuery/useMutation（由 react-query 提供）、TestContext/ra-test。
• bulkActionButtons迁移到<Datagrid>；currentSort改名sort；loading改名isLoading。
• <TranslationProvider>改名<I18nContextProvider>。

4.3 新增能力

requireAuth、basename、partial pagination（无total的分页）、useStore持久化偏好、Saved Queries、<ToggleThemeButton>、<LocalesMenuButton>、combineDataProvider、<ReferenceOneField>、<CustomRoutes>等均诞生于 v4。

五、从 CHANGELOG 提炼的功能演进时间线

CHANGELOG 的价值之一是能精确回答"某个能力是哪一版引入的"。以下是从中提炼的关键时间线：

5.1 安全修复必须关注

CHANGELOG 中标注了若干必须升级的安全版本：

• v4.7.6：<RichTextField>存在 XSS 漏洞，官方明确提示"如果你在服务端未净化富文本数据，必须升级到本版本"。
• v5.14.6：修复本地数据提供者（ra-data-local-storage等）中可能的原型污染赋值；同时修复escapePath的不完整字符串转义、<FormDataConsumer>的 ReDoS 风险、<RichTextField>标签剥离的指数级复杂度问题。
• 各版本大量Bump条目（如dompurify、axios、fast-uri、braces等）本质上是 dependabot 驱动的依赖安全升级，升级时建议一并跟进。

5.2 离线支持：v5 的一个隐形主线

从 v5.11.0 开始，CHANGELOG 密集出现"Add offline support to ..."条目，覆盖<ListBase>/<List>、<EditBase>/<Edit>、<ShowBase>/<Show>、<ReferenceField>、<ReferenceOneField>、<ReferenceInput>、<ReferenceArrayInput>、<ReferenceManyField>、<ReferenceManyCount>等几乎全部 CRUD 与引用组件，并伴随mutationKey的引入以支持离线 mutation。如果你需要做离线优先的管理后台，可以从这些版本对应的控制器源码（packages/ra-core/src/controller）入手研究实现细节。

六、v3 时代的印记：遥测机制与关闭方式

遥测机制于v3.11.0引入，并在 v4/v5 中保留。CHANGELOG 给出了官方说明与关闭示例，源码实现位于 CoreAdminUI.tsx：

• 应用挂载时会向https://react-admin-telemetry.marmelab.com/react-admin-telemetry发送一个匿名请求。
• 唯一发送的数据是 admin 域名（如example.com），不发送任何个人数据，请求不带 cookie。
• 以下情况不会发送遥测（源码条件）：disableTelemetry为真、非 production 环境、window/window.location/Image不可用（如 SSR）。

关闭方式：

// in src/App.js import * as React from "react"; import { Admin } from 'react-admin'; const App = () => ( <Admin disableTelemetry> {/* ... */} </Admin> );

七、最新 5.15.x 系列：小版本修复的阅读示范

CHANGELOG 尾部（5.15.3/5.15.2/5.15.1/5.15.0）展示了 react-admin 当前迭代节奏，也是"用 CHANGELOG 排查问题"的最佳范例：

• 5.15.3：<DataTable>在禁用批量删除时仍调用useCanAccess的修复；MUI v6 下<Notification>导致可撤销通知被提交两次的修复；<RichTextInput>编辑器重建时崩溃的修复。
• 5.15.2：大量<ReferenceField>组件抛出 "Maximum update depth exceeded" 的修复；useListController在鉴权检查期间重置已持久化页码的修复。
• 5.15.0：新增MUI v9 支持、ReferenceManyCountrender prop、<Translate>插值选项支持元素、ra-data-fakerest随机延迟、tiptap v3 升级。

阅读这些条目的实操意义：当你在最新版本中遇到某个组件异常时，先在本文件中搜索该组件名（例如DataTable、ReferenceField），即可知道它最近被改动过哪些行为、对应哪个 PR 号，再回到packages目录下的源码与.spec.tsx/.spec.ts测试文件核对实现与回归用例。

八、升级路线建议与信息索引

综合 CHANGELOG 内容，react-admin 应用的推荐升级路线是逐大版本跨越：

1. v3 → v4：处理 Context 化、prop 注入移除、react-hook-form 表单 API、MUI v5 主题等变更。
2. v4 → v5：处理 React 18 基线、rowClick默认值、bulkActionButtons位置、ESM 兼容（v5.13 的 Webpack/Vite/Jest 配置）等变更。
3. v5 内部小版本：重点关注安全修复（v4.7.6、v5.14.6 的规则延续）与工程配置更新（v5.13）。

每次升级后建议对照的仓库资源：

• 包导出与对外 API：packages/react-admin/src/index.ts
• 核心无头逻辑：packages/ra-core（auth、data、controller、form、list 等子目录）
• MUI 组件层：packages/ra-ui-materialui/src
• 构建与测试配置：package.json、jest.config.js、tsconfig.json
• 升级专项文档：docs/Upgrade.md

结语

CHANGELOG.md 不只是"谁改了什么"的记录，它是一份可追溯、可验证的版本技术档案：大版本条目包含迁移指南与配置片段，小版本条目精确到组件行为与 PR 编号。将它与packages目录下的源码、测试一一对照，你就能在升级、排障、移植功能时快速建立"版本 → 源码 → 行为"的完整映射，这正是本文希望通过梳理 3.x 到 5.x 的演进所呈现的核心方法论。

【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址: https://gitcode.com/gh_mirrors/re/react-admin