5分钟上手redux-little-router:Redux 路由快速入门完整指南

原创2026-10-15 12:53:501,638 阅读

5分钟上手redux-little-router:Redux 路由快速入门完整指南

🚀 redux-little-router 是一个专为 Redux 应用设计的轻量级路由方案,核心理念是"让 URL 开口说话"(let the URL do the talking)。本文将带你 5分钟完成安装、配置和接入,轻松掌握 Redux 路由的状态管理、页面导航与 React 组件用法,适合刚接触 React + Redux 技术栈的新手阅读。

一、什么是 redux-little-router?

在 React 应用里,路由(决定"当前显示哪个页面")通常由 React Router 这类视图层库接管,URL 状态被"锁"在组件树里,Redux 的 store 想读取当前 URL 却十分困难。

redux-little-router 用三条基本原则解决这个问题:

原则 含义
URL 是状态树的一员 当前路由状态存放在 state.router,任何 reducer、selector 都能直接读取
URL 变化就是普通 action 导航操作通过 dispatch action 完成,天然支持 redux-devtools 时间旅行调试
路由匹配简单可扩展 用 :param 占位符声明式定义路由,支持嵌套

它的核心不依赖任何视图库,同时提供灵活的 React 绑定组件(<Link>、<Fragment>),是 Redux 生态中把 URL 提升为"一等公民"的经典方案。

💡 项目状态说明:该项目自 2018 年 12 月起停止活跃维护(官方建议在 React Router 场景下考虑 connected-react-router),但作为理解"URL 状态进 Redux"的设计范例,它依然是学习 Redux 路由机制的绝佳教材。详见 README.md。

二、最快安装步骤:30秒完成配置

1. 安装依赖

在你的项目中执行:

npm install redux-little-router

如需源码研读,可克隆仓库(Node 版本需 >= 4):

git clone https://gitcode.com/gh_mirrors/re/redux-little-router
cd redux-little-router
yarn install

运行 yarn run demo 即可在 3000 端口启动官方演示应用,演示代码位于 demo/client/ 目录,其中的 demo/client/app.js 就是一份完整的最小接入示例。

2. 定义路由表

路由用"路由路径 → 任意数据"的哈希对象声明,支持嵌套:

const routes = {
  '/messages': { title: 'Message' },
  '/messages/:user': { title: 'Message History' },
  '/': {
    title: 'Home',
    '/bio': {
      '/:name': { title: 'Biography for:' }
    }
  }
};

匹配规则基于 url-pattern,:user、:name 就是参数占位符。每个路由值可以是任意可序列化数据(常用来存放页面标题等路由级数据)。

三、5分钟接入 Redux Store:核心三件套

redux-little-router 通过一个store enhancer(包装 history、监听 URL 变化)+ 一个middleware(拦截导航 action 并调用 history API)接入 Redux。三步搞定:

import { combineReducers, compose, createStore, applyMiddleware } from 'redux';
import { routerForBrowser, initializeCurrentLocation } from 'redux-little-router';

// ① 工厂方法生成 reducer / middleware / enhancer
const { reducer, middleware, enhancer } = routerForBrowser({ routes, basename: '/example' });

// ② 把 router 合并进全局 store
const store = createStore(
  combineReducers({ router: reducer }),
  initialState,
  compose(enhancer, applyMiddleware(middleware))
);

// ③ 客户端初始化当前 URL,触发首次路由匹配
const initialLocation = store.getState().router;
if (initialLocation) {
  store.dispatch(initializeCurrentLocation(initialLocation));
}

📌 步骤③是官方要求的客户端初始化动作,保证与 redux-thunk、redux-saga 等副作用类 enhancer 兼容。

不同环境使用不同的工厂方法,源码中都有对应实现:

工厂方法 适用场景 源码位置
routerForBrowser 纯浏览器 SPA src/environment/browser-router.js
routerForHash hash 路由(#/path 风格) src/environment/hash-router.js
routerForExpress Node.js 服务端渲染(Express) src/environment/express-router.js
routerForHapi Node.js 服务端渲染(Hapi) src/environment/hapi-router.js

所有导出集中在 src/index.js,类型定义见 index.d.ts。

四、Redux 路由状态速览:读懂 state.router

每次 URL 变化,enhancer 都会 dispatch 一个 LOCATION_CHANGED action,reducer 把结果写入 state.router,结构如下:

state.router = {
  pathname: '/messages/a-user',   // 当前路径
  route: '/messages/:user',       // 命中的路由模板
  params: { user: 'a-user' },     // 解析出的路径参数
  query: { some: 'thing' },       // 解析后的查询参数
  search: '?some=thing',          // 原始查询字符串
  result: { title: '...' },       // 路由表中你定义的数据
  previous: { /* 上一个 location 的完整快照 */ }
};

这意味着:

  • selector 直接取参:state.router.params.user 比在组件 props 里层层传递更直接;
  • 对比前后路由:router.previous 让你轻松做"进入页面时加载数据"的逻辑;
  • 路由级数据:result 字段承载你在路由表里配置的任意数据,适合管理页面标题。

reducer 的合并逻辑(query 持久化、basename 处理、previous 记录)可参考 src/reducer.js。

五、导航 API 清单:一行代码切换页面

库内置了一组公开的 action creator(定义于 src/actions.js),在任意能拿到 dispatch 的地方调用即可:

API 作用 类比 History API
push(href) 跳转并新增历史记录 pushState
replace(href) 跳转但不新增历史记录 replaceState
go(n) / goBack() / goForward() 前进 / 后退 n 步 history.go
block(fn) / unblock() 离开页面时弹窗拦截确认 history blocking
replaceRoutes(routes) 运行时动态替换整个路由表 用于代码分割

常用技巧:

  • 传对象:push({ pathname: '/messages', query: { filter: 'business' } }),query 对象会被序列化进 URL;
  • 保留查询参数:第二个参数传 { persistQuery: true },跳转后沿用上一页面的 query;
  • 配合 thunk 做重定向:dispatch(push('/login')) 一行完成,无需任何视图层 API。

六、React 绑定: 与 组件

核心与 React 解耦,但库内置了两个"自带 connect()"的组件,让视图层同样省心(源码见 src/components/):

:可点击的导航链接

<Link href="/messages" activeProps={{ className: 'active' }}>
  消息
</Link>
  • 点击即 dispatch 导航 action,自动尊重右键/修饰键默认行为;
  • activeProps 在链接命中当前路由时附加样式,轻松实现"高亮当前页";
  • 兄弟组件 <PersistentQueryLink> 会在跳转时保留现有 query string。

:按条件渲染当前页面

<Fragment> 可理解为"轻量版 <Route>",能放在组件树的任何位置:

<Fragment forRoute="/messages/:team">
  <TeamMessages />
</Fragment>

<Fragment withConditions={loc => loc.query.superuser}>
  <SuperUserBadge />
</Fragment>

<Fragment forNoMatch />  {/* 404 页面:所有路由都未命中时渲染 */}

嵌套 <Fragment> 可以与嵌套路由表一一对应,非常适合做"页中页"的分栏布局。

七、进阶玩法:SSR、immutable 与代码分割

  • 服务端渲染:用 routerForExpress / routerForHapi 把请求传进工厂方法,客户端再用 routerForBrowser 恢复状态,完整流程见 ADVANCED.md(演示服务代码在 demo/server/);
  • immutable 支持:配合 redux-immutable 使用时,从 redux-little-router/es/immutable 导入 immutableRouterForBrowser 等对应版本,源码位于 src/immutable/;
  • 代码分割:动态加载组件后用 replaceRoutes 注册新路由,建议配合 lodash.merge 合并旧路由表,避免"一刀切"清空;
  • 运行时路由校验:src/util/validate-routes.js 会在配置错误时给出明确报错,路由匹配缓存逻辑见 src/util/match-cache.js。

八、常见问题 FAQ

Q:和 React Router 冲突吗? 不冲突,但官方建议:若你更看重 React Router 的组件 API 生态,可优先考虑 connected-react-router;若希望"URL 完全由 Redux 驱动",本库的设计更纯粹。

Q:最低环境要求是什么? ES5 兼容环境即可(不支持 IE8),React 0.14 / 15 / 16、redux 3+ 均支持(见 package.json 的 peerDependencies)。

Q:项目版本迭代频繁是为什么? 项目遵循严格 semver,任何破坏性变更(无论多小)都会升主版本号,高版本号不代表方向性转变。

九、写在最后

回顾一下本文的 5 分钟路线:安装依赖 → 声明路由表 → routerForBrowser 生成三件套 → 合并进 store 并初始化 URL → 用 push 等 API 和 <Link>/<Fragment> 组件完成导航。掌握"URL 即状态"这一心智模型后,你会发现 Redux 时间旅行调试、路由级数据驱动、前后端同构等场景都变得顺理成章。

📂 想深入源码?推荐阅读顺序:src/index.js(全部导出)→ src/enhancer.js(URL 监听)→ src/middleware.js(导航拦截)→ src/reducer.js(状态合并)。祝上手愉快!

登录后查看全文
redux-little-router