React Router v7 需要以下最低版本
node@20react@18react-dom@18如果您已启用所有未来特性标志，则 v7 升级没有破坏性更改。这些标志允许您一次更新应用程序的一个更改。我们强烈建议您在每个步骤之后提交并发布，而不是一次完成所有操作。
首先更新到最新的 v6.x 小版本，以拥有最新的未来特性标志和控制台警告。
👉 更新到最新的 v6
npm install react-router-dom@6
背景
更改多段 splat 路径（如 dashboard/*，而不是仅 *）的相对路径匹配和链接。查看更新日志了解更多信息。
👉 启用标志
启用标志取决于路由器的类型
<BrowserRouter
future={{
v7_relativeSplatPath: true,
}}
/>
createBrowserRouter(routes, {
future: {
v7_relativeSplatPath: true,
},
});
更新您的代码
如果您有任何带有路径 + splat 的路由，例如 <Route path="dashboard/*">，并且在其下方有相对链接，例如 <Link to="relative"> 或 <Link to="../relative">，则需要更新您的代码。
👉 将 <Route> 拆分为两个
将任何多段 splat <Route> 拆分为带有路径的父路由和带有 splat 的子路由
<Routes>
<Route path="/" element={<Home />} />
- <Route path="dashboard/*" element={<Dashboard />} />
+ <Route path="dashboard">
+ <Route path="*" element={<Dashboard />} />
+ </Route>
</Routes>
// or
createBrowserRouter([
{ path: "/", element: <Home /> },
{
- path: "dashboard/*",
- element: <Dashboard />,
+ path: "dashboard",
+ children: [{ path: "*", element: <Dashboard /> }],
},
]);
👉 更新相对链接
更新该路由树内的任何 <Link> 元素，以包含额外的 .. 相对段，以继续链接到相同的位置
function Dashboard() {
return (
<div>
<h2>Dashboard</h2>
<nav>
- <Link to="/">Dashboard Home</Link>
- <Link to="team">Team</Link>
- <Link to="projects">Projects</Link>
+ <Link to="../">Dashboard Home</Link>
+ <Link to="../team">Team</Link>
+ <Link to="../projects">Projects</Link>
</nav>
<Routes>
<Route path="/" element={<DashboardHome />} />
<Route path="team" element={<DashboardTeam />} />
<Route
path="projects"
element={<DashboardProjects />}
/>
</Routes>
</div>
);
}
背景
这使用 React.useTransition 而不是 React.useState 进行 Router 状态更新。查看更新日志了解更多信息。
👉 启用标志
<BrowserRouter
future={{
v7_startTransition: true,
}}
/>
// or
<RouterProvider
future={{
v7_startTransition: true,
}}
/>
👉 更新您的代码
除非您在组件内部使用 React.lazy，否则无需更新任何内容。
在组件内部使用 React.lazy 与 React.useTransition（或其他在组件内部生成 promise 的代码）不兼容。将 React.lazy 移动到模块作用域，并停止在组件内部生成 promise。这不是 React Router 的限制，而是 React 的不正确用法。
<RouterProvider>，则可以跳过此步骤
背景
Fetcher 生命周期现在基于它何时返回空闲状态，而不是其所有者组件何时卸载：查看更新日志了解更多信息。
启用标志
createBrowserRouter(routes, {
future: {
v7_fetcherPersist: true,
},
});
更新您的代码
不太可能影响您的应用程序。您可能需要检查 useFetchers 的任何用法，因为它们可能会比以前持续更长时间。根据您正在执行的操作，您可能会渲染比以前更长时间的内容。
<RouterProvider>，则可以跳过此步骤
这会将 formMethod 字段规范化为大写 HTTP 方法，以与 fetch() 行为对齐。查看更新日志了解更多信息。
👉 启用标志
createBrowserRouter(routes, {
future: {
v7_normalizeFormMethod: true,
},
});
更新您的代码
如果您的任何代码正在检查小写 HTTP 方法，则需要更新它以检查大写 HTTP 方法（或在其上调用 toLowerCase()）。
👉 将 formMethod 与大写进行比较
-useNavigation().formMethod === "post"
-useFetcher().formMethod === "get";
+useNavigation().formMethod === "POST"
+useFetcher().formMethod === "GET";
<RouterProvider>，则可以跳过此步骤
这启用了数据路由器的部分水合，主要用于 SSR 框架，但如果您使用 lazy 加载路由模块，它也很有用。您不太可能需要担心这一点，只需打开标志即可。查看更新日志了解更多信息。
👉 启用标志
createBrowserRouter(routes, {
future: {
v7_partialHydration: true,
},
});
更新您的代码
使用部分水合，您需要提供一个 HydrateFallback 组件，以便在初始水合期间渲染。此外，如果您之前使用了 fallbackElement，则需要删除它，因为它现在已弃用。在大多数情况下，您会希望重用 fallbackElement 作为 HydrateFallback。
👉 将 fallbackElement 替换为 HydrateFallback
const router = createBrowserRouter(
[
{
path: "/",
Component: Layout,
+ HydrateFallback: Fallback,
// or
+ hydrateFallbackElement: <Fallback />,
children: [],
},
],
);
<RouterProvider
router={router}
- fallbackElement={<Fallback />}
/>
createBrowserRouter，则可以跳过此步骤
启用此标志后，在操作抛出/返回状态代码为 4xx/5xx 的 Response 后，加载器将不再默认重新验证。您可以通过 shouldRevalidate 和 actionStatus 参数选择在这些场景中重新验证。
👉 启用标志
createBrowserRouter(routes, {
future: {
v7_skipActionErrorRevalidation: true,
},
});
更新您的代码
在大多数情况下，您可能不必更改应用程序代码。通常，如果操作出错，则不太可能数据被修改并且需要重新验证。如果您的任何代码确实在操作错误场景中修改了数据，则您有 2 个选项
👉 选项 1：更改 action 以避免在错误场景中进行修改
// Before
async function action() {
await mutateSomeData();
if (detectError()) {
throw new Response(error, { status: 400 });
}
await mutateOtherData();
// ...
}
// After
async function action() {
if (detectError()) {
throw new Response(error, { status: 400 });
}
// All data is now mutated after validations
await mutateSomeData();
await mutateOtherData();
// ...
}
👉 选项 2：通过 shouldRevalidate 和 actionStatus 选择重新验证
async function action() {
await mutateSomeData();
if (detectError()) {
throw new Response(error, { status: 400 });
}
await mutateOtherData();
}
async function loader() { ... }
function shouldRevalidate({ actionStatus, defaultShouldRevalidate }) {
if (actionStatus != null && actionStatus >= 400) {
// Revalidate this loader when actions return a 4xx/5xx status
return true;
}
return defaultShouldRevalidate;
}
json 和 defer 方法已被弃用，建议返回原始对象。
async function loader() {
- return json({ data });
+ return { data };
如果您使用 json 将数据序列化为 JSON，则可以使用原生 Response.json() 方法代替。
现在您的应用程序已赶上进度，您可以简单地更新到 v7（理论上！）而不会出现问题。
👉 安装 v7
npm install react-router-dom@latest
👉 将 react-router-dom 替换为 react-router
在 v7 中，我们不再需要 "react-router-dom"，因为包已简化。您可以从 "react-router" 导入所有内容
npm uninstall react-router-dom
npm install react-router@latest
请注意，您只需要在 package.json 中使用 "react-router"。
👉 更新导入
现在您应该更新您的导入以使用 react-router
-import { useLocation } from "react-router-dom";
+import { useLocation } from "react-router";
您可以改用此命令手动更新导入。但请确保您的 git 工作树是干净的，以便在它没有按预期工作时可以恢复。
find ./path/to/src \( -name "*.tsx" -o -name "*.ts" -o -name "*.js" -o -name "*.jsx" \) -type f -exec sed -i '' 's|from "react-router-dom"|from "react-router"|g' {} +
如果您安装了 GNU sed（大多数 Linux 发行版），请改用此命令
find ./path/to/src \( -name "*.tsx" -o -name "*.ts" -o -name "*.js" -o -name "*.jsx" \) -type f -exec sed -i 's|from "react-router-dom"|from "react-router"|g' {} +
👉 更新 DOM 特定导入
RouterProvider 和 HydratedRouter 来自深层导入，因为它们依赖于 "react-dom"
-import { RouterProvider } from "react-router-dom";
+import { RouterProvider } from "react-router/dom";
请注意，对于非 DOM 上下文（例如 Jest 测试），您应该使用顶级导入
-import { RouterProvider } from "react-router-dom";
+import { RouterProvider } from "react-router";
恭喜，您现在已升级到 v7！