tarojs-router-next

tarojs-router-next#

资源概述#

tarojs-router-next 是一款专为 Taro 小程序框架设计的路由增强库，由开发者 lblblong 创建并维护。它通过编译时插件自动生成类型安全的路由方法，解决了原生小程序路由开发的四大痛点：URL 无类型提示易出错、参数传递类型/大小受限、异步路由通信复杂、鉴权拦截实现困难。截至 2026 年 8 月，项目在 GitHub 获得 252 星标，npm 发布了 50 个版本，最近一次发布为 2026 年 7 月。支持 Taro 全框架（React / Vue / Vue3 / Nerv），已在微信、QQ、支付宝小程序测试通过，同时支持 H5 端。

设计规范#

零配置类型安全：编译插件监听 src/pages 目录变化，自动生成带参数类型提示的 Router.to** 方法，开发者无需手写页面 URL
任意数据传递：通过 data 参数可传递任意类型、任意大小的数据（基于 EventChannel 实现），突破原生路由参数只能拼接到 URL 的限制
同步路由调用：路由跳转返回 Promise，可用 async/await 编写同步风格代码，替代原生 EventChannel 回调模式
Koa 风格中间件：提供 Router.middleware() API，支持以洋葱模型组织鉴权、日志、性能监控等横切逻辑

审核规范#

不适用（工具库，非平台）。

开发指南#

快速上手#

code

// 1. 安装依赖
// npm install --save tarojs-router-next
// npm install --dev tarojs-router-next-plugin

// 2. 配置 Taro 编译插件（config/index.js）
const config = {
  plugins: ['tarojs-router-next-plugin'],
}

// 3. 使用自动生成的路由方法（假设有 src/pages/detail/index.tsx）
import { Router } from 'tarojs-router-next'

// 自动生成 Router.toDetail 方法，参数有类型提示
Router.toDetail({
  params: { id: 123 },   // URL 参数，自动拼接到路径
  data: { bigData: [...] } // 任意类型/大小数据，通过 EventChannel 传递
})

// 4. 在目标页面接收数据
import { Router } from 'tarojs-router-next'
const { params, data } = Router.getData()

路由中间件示例#

code

// 鉴权中间件
Router.middleware({
  to: ['toProfile', 'toOrder'], // 仅拦截指定路由
}, async (ctx, next) => {
  if (!isLogin()) {
    Router.toLogin()
    return // 中断路由
  }
  await next() // 继续执行
})

// 日志中间件
Router.middleware(async (ctx, next) => {
  console.log('导航开始:', ctx.route.url)
  await next()
  console.log('导航完成')
})

常见陷阱#

编译插件必须配置：不配置 tarojs-router-next-plugin 则 Router.to** 方法不会生成，运行时报错
React Native 不支持：目前仅支持小程序和 H5 端，React Native 端暂不可用
中间件执行顺序：中间件按注册顺序执行（洋葱模型），next() 之前的代码先执行，之后后执行
EventChannel 数据量：虽然 data 参数支持任意类型，但实际传输受小程序内存限制，超大对象可能导致性能问题

生态资源#

配套工具#

tarojs-router-next-plugin：编译插件，必须配合核心包使用
Taroify：Vant 的 Taro 版本 UI 库，与本库搭配可构建完整 Taro 开发栈

社区资源#

GitHub Issues：问题反馈和功能建议
在线文档站：https://lblblong.github.io/tarojs-router-next

版本更新#

v3.4.7（最新）：npm 50 个版本持续迭代，最近发布 2026-07-11
持续跟进 Taro 版本升级，适配 Taro 3.x 编译体系
支持 Taro 全框架（React / Vue / Vue3 / Nerv）
已在微信、QQ、支付宝小程序 + H5 端测试通过

详细文档