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?？梢妰蓷l 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），僅供參考