单页应用路由还在自己解析地址栏,React Router 官方怎么起步?

单页应用的地址栏路由还在自己解析。按现行官方安装入口,把 framework 和 declarative 分开,再按项目情况选一条。不要把还能打开的 v6 旧文档当成当前默认,也不是再盘一遍浏览器自带的 Web API。

React Router Home 把它写成面向 React 的多策略路由库:可以当成一套 React 框架来用,也可以按需要只用很薄的一层。现行入门不是只给一条路,而是三种 mode:Declarative、Data、Framework。文档正文里会用对应图标标明某一段说明适用于哪种 mode。文档站点的版本切换里,当前 latest 标的是 8.5.1,另外还能看到 7.18.5 和 6.30.6。若打开旧路径 /docs/en/v6/start/overview,会落到 Feature Overview v6.30.6,页上写着 Viewing docs for an older release。那份概览可以当历史对照,不要再把它当作现在的默认起步页。主页的升级说明写的是:如果已经跟上 future flags,从 React Router v7 升级通常是非破坏性的,可见现行文档默认讲的已经不是 v6 那一套。

三种用法怎么选,主页指向 Picking a Mode。页里说能力是累加的:从 Declarative 到 Data 再到 Framework,功能变多,你对架构的掌控就相应减少,按自己想要多少帮助、留多少控制权来选即可。跟是不是一定要 SSR 关系不大,三种 mode 都支持不同架构和部署目标。

Declarative 提供基础的那一层:把 URL 对上组件、在应用里跳转,还有激活态。顶层 API 是 BrowserRouter,再配合 Route、useNavigate、useLocation 这类接口。官方建议在这些情况下用它。一种是只想尽可能简单地用 React Router。一种是从更早的版本过来,而且对 BrowserRouter 这种写法已经满意。再一种是你已经有自己的数据层(例如本地优先、后台同步,或自己有一套挂起态抽象)。安装入口是 Declarative Installation。可以先用 npx create-vite@latest 起一个 Vite 的 React 模板(或按自己偏好的方式搭应用),再执行 npm i react-router,最后在渲染根节点时用 BrowserRouter 把应用包起来。官方示例是从 react-router 引入 BrowserRouter,再写成:

import { BrowserRouter } from "react-router";

ReactDOM.createRoot(root).render(
  <BrowserRouter>
    <App />
  </BrowserRouter>,
);

注意现行包名是 react-router。v6 那份概览里的示例还在从 react-router-dom 引入 createBrowserRouter,不要顺着旧文档把那个包名当成当前默认。

Framework 则是在 Data mode 外面再包一层 Vite 插件,用来补上类型安全的 href 和 Route Module API、按路由做代码分割,以及 SPA、SSR、静态输出这些策略。官方建议:还没形成偏好、只是想用 React 把东西做出来,或者正在拿它和 Next.js、SvelteKit、Astro 这类方案对比时,走 Framework。安装入口是 Framework Installation,常用命令是 npx create-react-router@latest my-react-router-app,然后进入目录执行 npm i 和 npm run dev,再在浏览器打开 http://localhost:5173。能打开这个本地地址,就说明模板已经跑起来了。官方也提供一批可部署的模板,命令形态是 npx create-react-router@latest --template remix-run/react-router-templates/<template-name>。想看模板如何手工搭起来,安装页指向这份模板在 GitHub 上的源码。declarative 和 framework 两份安装页的下一步都指向 Routing,路由怎么声明要进对应文档再看,这里只把起步方式分开。

Data mode 夹在两者中间:把路由配置从 React 渲染里拿出来,用 createBrowserRouter 和 RouterProvider,并带上 loader、action、useFetcher 这类数据接口。选型页给它的建议是:想要数据相关能力,同时又想自己掌控打包、数据和服务器抽象。或者在 v6.4 里已经用上 data router、并且用得还满意。Framework 安装页则直接写了:大多数项目会从一份模板起步,所以默认命令用的是官方维护的那份基础模板。主页把三种入口并列写出,但就地址栏还在自己解析、想先跑起来这一点,更常见的分岔仍是下面两条。已经有一份 Vite 或其它 React 应用、只想补一层路由,就对着 declarative 的安装页做。新项目没有既有脚手架包袱,按官方建议从 framework 那条 create-react-router 命令起,而不是回去翻 v6 的 Feature Overview。

你们现在这份应用,是打算在已有 Vite 项目里先用 BrowserRouter,还是直接走 create-react-router?

npm i react-router-dom

createBrowserRouter 写路由表,RouterProvider 挂最外层。

v6 之后 Switch 和 component 都废了,改成 Routes 和 element,从老项目平移过来最容易在这里报错。