Refine v5 迁移指南从 refinedev/react-router-v6 平滑升级到 React Router v7【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine本指南基于 documentation/docs/routing/integrations/react-router/migration-guide-v6-to-v7.md系统讲解如何将基于refinedev/react-router-v6React Router v6的 Refine 项目迁移到refinedev/react-routerReact Router v7。你将掌握包替换、依赖更新、import 改写的完整步骤以及如何借助官方refine-codemod一键完成自动迁移并深入了解新包在仓库源码层面的导出结构与工作原理。迁移概览这次升级到底改了什么对于使用 React Router 的 Refine 项目来说v6 → v7 的升级核心是一次包层面的重新组织而不是 API 的大规模重写包名变更refinedev/react-router-v6更名为refinedev/react-router目的是与其他 Refine 集成包的命名保持一致避免混淆底层依赖变更React Router 官方在 v7 中将react-router-dom合并进react-router因此项目中不再需要安装react-router-dom所有组件统一从react-router导入Refine 自身无破坏性变更迁移指南明确指出除包名变化外Refine 并未引入其他 breaking changes因此迁移工作的重心是依赖替换与 import 更新。至于 React Router v7 自身的破坏性变化如 Data APIs、未来标志等官方建议阅读 React Router v7 的迁移文档进一步确认。从当前仓库的实际状态看新包 packages/react-router/package.json 的依赖为react-router: ^7.0.2peerDependencies 同样要求react-router: ^7.0.2并且refinedev/core的 peer 版本为^5.0.0即新包面向 Refine v5 生态。第一步卸载旧包迁移的第一步是移除旧版相关的三个包。由于 v7 中react-router已合并了原react-router-dom的能力三者都需要从项目中卸载npm uninstall refinedev/react-router-v6 react-router-dom react-router若项目使用 pnpm 或 yarn将npm uninstall替换为对应的pnpm remove或yarn remove即可原理一致。第二步安装新包卸载完成后安装新的集成包与 React Router v7。注意这里不再需要安装react-router-dom所有 v7 组件RouterProvider、BrowserRouter、Routes、Route、Outlet、Link等均从react-router包导入npm install refinedev/react-router react-router安装完成后package.json中的依赖变化对应如下- refinedev/react-router-v6: ^4.6.0 refinedev/react-router: ^1.0.1 - react-router-dom: ^6.8.1 - react-router: ^6.8.1 react-router: ^7.0.2完成以上两步后基础迁移即告完成可以开始使用refinedev/react-router搭配react-routerv7 编写路由。第三步更新 import 语句包替换后所有相关 import 需要同步更新主要涉及两类来源import routerProvider, { NavigateToResource, UnsavedChangesNotifier, DocumentTitleHandler } - from refinedev/react-router-v6; from refinedev/react-router; -import { RouterProvider } from react-router-dom; import { RouterProvider } from react-router;RouterProvider是典型的受影响示例v6 时代它从react-router-dom导出v7 中改从react-router导出。除此之外BrowserRouter、Routes、Route、Outlet、Link、Navigate、useNavigate、useLocation、useParams等组件与 hooks 的导入来源也都应改为react-router。推荐方案用 refine-codemod 自动改写 import手动逐个文件更新 import 容易遗漏官方推荐使用refine-codemod自动完成替换。该工具基于 jscodeshift 实现源码级 AST 转换可以精准改写所有命中的 import 声明。使用前请确保 git 工作区干净以便迁移不符合预期时可以回退。针对本次迁移需要依次执行两条 codemod# 将 refinedev/react-router-v6 改写为 refinedev/react-router npx refinedev/codemodlatest refine-react-router-v6-to-refine-react-router # 将 react-router-dom 改写为 react-router npx refinedev/codemodlatest react-router-dom-to-react-router从仓库源码可以确认这两条 codemod 的实际行为在 packages/codemod/src/index.ts 中注册了对应名称其转换逻辑分别位于 refine-react-router-v6-to-refine-react-router.ts 与 react-router-dom-to-react-router.tsrefine-react-router-v6-to-refine-react-router查找source为refinedev/react-router-v6的ImportDeclaration原样保留 import specifiers仅将模块名替换为refinedev/react-routerreact-router-dom-to-react-router查找source为react-router-dom的ImportDeclaration将模块名替换为react-router。可见两条 codemod 都只做模块来源的精准替换不会改动你导入的具名符号迁移后代码语义保持不变。迁移后的源码级认知refinedev/react-router 导出了什么迁移完成后新包在仓库中的核心实现位于 packages/react-router/src/index.ts从中可以看到包的公开导出面这也是迁移后你在项目中可以继续使用的全部能力export { routerProvider as default, stringifyConfig } from ./bindings.js; export { NavigateToResource } from ./navigate-to-resource.js; export { UnsavedChangesNotifier } from ./unsaved-changes-notifier.js; export { CatchAllNavigate } from ./catch-all-navigate.js; export { DocumentTitleHandler } from ./document-title-handler.js; export { useDocumentTitle } from ./use-document-title.js;routerProvider默认导出传给Refine routerProvider{routerProvider}的路由桥接层实现go、back、parse、Link四个核心能力。其实现位于 bindings.tsxgo基于useNavigate构造目标 URL支持query、hash、keepQuery、keepHash等配置parse结合matchResourceFromRoute与qs解析出当前resource、action、id与分页参数Link直接转发react-router的LinkNavigateToResource跳转到指定资源的 list 页面常用于应用根路由UnsavedChangesNotifier配合options.warnWhenUnsavedChanges: true实现未保存更改的离开提醒含beforeunload场景CatchAllNavigate重定向到指定路径并将当前 location 以to查询参数保留以便回跳实现见 catch-all-navigate.tsxDocumentTitleHandler与useDocumentTitle按资源与动作自动生成页面标题也支持自定义handler与 i18n 键。这些组件的具体用法含认证路由、布局、Access Control、错误页、根路由等场景可继续参考 documentation/docs/routing/integrations/react-router/index.md。迁移后的基本用法验证完成迁移后一个最小可用形态如下演示BrowserRouter风格均从react-router导入import { Refine } from refinedev/core; import dataProvider from refinedev/simple-rest; import routerProvider from refinedev/react-router; import { BrowserRouter, Routes, Route } from react-router; import { PostList, PostCreate } from pages/posts; const App () { return ( BrowserRouter Refine dataProvider{dataProvider} routerProvider{routerProvider} resources{[ { name: posts, list: /posts, create: /posts/create, }, ]} Routes Route pathposts Route index element{PostList /} / Route pathcreate element{PostCreate /} / /Route /Routes /Refine /BrowserRouter ); };若项目使用 React Router v7 的 Data APIscreateBrowserRouterRouterProvider同样全部从react-router导入即可routerProvider的传参方式不变。注意事项与后续动作React Router v7 自身的破坏性变更refinedev/react-router只负责 Refine 与 React Router 的桥接不屏蔽 React Router v7 本身的变更如未来标志、Data APIs 行为等迁移后建议按 React Router v7 迁移文档核对项目中直接使用的路由 API版本对齐从仓库的 package.json 可见新包要求 Node20、react ^18 || ^19、refinedev/core ^5.0.0请确保项目环境满足这些约束codemod 的可回退性自动改写是批量源码修改执行前务必确认 git 工作区干净改完后先跑一遍类型检查tsc --noEmit与构建再提交组件与 hooks 不受影响NavigateToResource、UnsavedChangesNotifier、CatchAllNavigate、DocumentTitleHandler、useDocumentTitle的 API 均保持不变业务代码中除 import 来源外无需额外改动。至此你的 Refine 项目已平滑完成从 React Router v6 到 v7 的迁移包名统一、依赖精简、import 规整并且可以继续享受 Refine 路由桥接层提供的全部能力。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/12 23:58:50 · 阅读 1.2k Refine v5 迁移指南：从 @refinedev/react-router-v6 平滑升级到 React Router v7
Refine v5 迁移指南从 refinedev/react-router-v6 平滑升级到 React Router v7【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine本指南基于 documentation/docs/routing/integrations/react-router/migration-guide-v6-to-v7.md系统讲解如何将基于refinedev/react-router-v6React Router v6的 Refine 项目迁移到refinedev/react-routerReact Router v7。你将掌握包替换、依赖更新、import 改写的完整步骤以及如何借助官方refine-codemod一键完成自动迁移并深入了解新包在仓库源码层面的导出结构与工作原理。迁移概览这次升级到底改了什么对于使用 React Router 的 Refine 项目来说v6 → v7 的升级核心是一次包层面的重新组织而不是 API 的大规模重写包名变更refinedev/react-router-v6更名为refinedev/react-router目的是与其他 Refine 集成包的命名保持一致避免混淆底层依赖变更React Router 官方在 v7 中将react-router-dom合并进react-router因此项目中不再需要安装react-router-dom所有组件统一从react-router导入Refine 自身无破坏性变更迁移指南明确指出除包名变化外Refine 并未引入其他 breaking changes因此迁移工作的重心是依赖替换与 import 更新。至于 React Router v7 自身的破坏性变化如 Data APIs、未来标志等官方建议阅读 React Router v7 的迁移文档进一步确认。从当前仓库的实际状态看新包 packages/react-router/package.json 的依赖为react-router: ^7.0.2peerDependencies 同样要求react-router: ^7.0.2并且refinedev/core的 peer 版本为^5.0.0即新包面向 Refine v5 生态。第一步卸载旧包迁移的第一步是移除旧版相关的三个包。由于 v7 中react-router已合并了原react-router-dom的能力三者都需要从项目中卸载npm uninstall refinedev/react-router-v6 react-router-dom react-router若项目使用 pnpm 或 yarn将npm uninstall替换为对应的pnpm remove或yarn remove即可原理一致。第二步安装新包卸载完成后安装新的集成包与 React Router v7。注意这里不再需要安装react-router-dom所有 v7 组件RouterProvider、BrowserRouter、Routes、Route、Outlet、Link等均从react-router包导入npm install refinedev/react-router react-router安装完成后package.json中的依赖变化对应如下- refinedev/react-router-v6: ^4.6.0 refinedev/react-router: ^1.0.1 - react-router-dom: ^6.8.1 - react-router: ^6.8.1 react-router: ^7.0.2完成以上两步后基础迁移即告完成可以开始使用refinedev/react-router搭配react-routerv7 编写路由。第三步更新 import 语句包替换后所有相关 import 需要同步更新主要涉及两类来源import routerProvider, { NavigateToResource, UnsavedChangesNotifier, DocumentTitleHandler } - from refinedev/react-router-v6; from refinedev/react-router; -import { RouterProvider } from react-router-dom; import { RouterProvider } from react-router;RouterProvider是典型的受影响示例v6 时代它从react-router-dom导出v7 中改从react-router导出。除此之外BrowserRouter、Routes、Route、Outlet、Link、Navigate、useNavigate、useLocation、useParams等组件与 hooks 的导入来源也都应改为react-router。推荐方案用 refine-codemod 自动改写 import手动逐个文件更新 import 容易遗漏官方推荐使用refine-codemod自动完成替换。该工具基于 jscodeshift 实现源码级 AST 转换可以精准改写所有命中的 import 声明。使用前请确保 git 工作区干净以便迁移不符合预期时可以回退。针对本次迁移需要依次执行两条 codemod# 将 refinedev/react-router-v6 改写为 refinedev/react-router npx refinedev/codemodlatest refine-react-router-v6-to-refine-react-router # 将 react-router-dom 改写为 react-router npx refinedev/codemodlatest react-router-dom-to-react-router从仓库源码可以确认这两条 codemod 的实际行为在 packages/codemod/src/index.ts 中注册了对应名称其转换逻辑分别位于 refine-react-router-v6-to-refine-react-router.ts 与 react-router-dom-to-react-router.tsrefine-react-router-v6-to-refine-react-router查找source为refinedev/react-router-v6的ImportDeclaration原样保留 import specifiers仅将模块名替换为refinedev/react-routerreact-router-dom-to-react-router查找source为react-router-dom的ImportDeclaration将模块名替换为react-router。可见两条 codemod 都只做模块来源的精准替换不会改动你导入的具名符号迁移后代码语义保持不变。迁移后的源码级认知refinedev/react-router 导出了什么迁移完成后新包在仓库中的核心实现位于 packages/react-router/src/index.ts从中可以看到包的公开导出面这也是迁移后你在项目中可以继续使用的全部能力export { routerProvider as default, stringifyConfig } from ./bindings.js; export { NavigateToResource } from ./navigate-to-resource.js; export { UnsavedChangesNotifier } from ./unsaved-changes-notifier.js; export { CatchAllNavigate } from ./catch-all-navigate.js; export { DocumentTitleHandler } from ./document-title-handler.js; export { useDocumentTitle } from ./use-document-title.js;routerProvider默认导出传给Refine routerProvider{routerProvider}的路由桥接层实现go、back、parse、Link四个核心能力。其实现位于 bindings.tsxgo基于useNavigate构造目标 URL支持query、hash、keepQuery、keepHash等配置parse结合matchResourceFromRoute与qs解析出当前resource、action、id与分页参数Link直接转发react-router的LinkNavigateToResource跳转到指定资源的 list 页面常用于应用根路由UnsavedChangesNotifier配合options.warnWhenUnsavedChanges: true实现未保存更改的离开提醒含beforeunload场景CatchAllNavigate重定向到指定路径并将当前 location 以to查询参数保留以便回跳实现见 catch-all-navigate.tsxDocumentTitleHandler与useDocumentTitle按资源与动作自动生成页面标题也支持自定义handler与 i18n 键。这些组件的具体用法含认证路由、布局、Access Control、错误页、根路由等场景可继续参考 documentation/docs/routing/integrations/react-router/index.md。迁移后的基本用法验证完成迁移后一个最小可用形态如下演示BrowserRouter风格均从react-router导入import { Refine } from refinedev/core; import dataProvider from refinedev/simple-rest; import routerProvider from refinedev/react-router; import { BrowserRouter, Routes, Route } from react-router; import { PostList, PostCreate } from pages/posts; const App () { return ( BrowserRouter Refine dataProvider{dataProvider} routerProvider{routerProvider} resources{[ { name: posts, list: /posts, create: /posts/create, }, ]} Routes Route pathposts Route index element{PostList /} / Route pathcreate element{PostCreate /} / /Route /Routes /Refine /BrowserRouter ); };若项目使用 React Router v7 的 Data APIscreateBrowserRouterRouterProvider同样全部从react-router导入即可routerProvider的传参方式不变。注意事项与后续动作React Router v7 自身的破坏性变更refinedev/react-router只负责 Refine 与 React Router 的桥接不屏蔽 React Router v7 本身的变更如未来标志、Data APIs 行为等迁移后建议按 React Router v7 迁移文档核对项目中直接使用的路由 API版本对齐从仓库的 package.json 可见新包要求 Node20、react ^18 || ^19、refinedev/core ^5.0.0请确保项目环境满足这些约束codemod 的可回退性自动改写是批量源码修改执行前务必确认 git 工作区干净改完后先跑一遍类型检查tsc --noEmit与构建再提交组件与 hooks 不受影响NavigateToResource、UnsavedChangesNotifier、CatchAllNavigate、DocumentTitleHandler、useDocumentTitle的 API 均保持不变业务代码中除 import 来源外无需额外改动。至此你的 Refine 项目已平滑完成从 React Router v6 到 v7 的迁移包名统一、依赖精简、import 规整并且可以继续享受 Refine 路由桥接层提供的全部能力。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考