告别复杂路由！uni-simple-router：轻量级uni-app路由解决方案

2026-01-29 12:01:06作者：裘晴惠Vivianne

你是否还在为uni-app项目中的路由管理感到困扰？原生路由API功能有限，第三方库又过于臃肿？本文将为你介绍一款专为uni-app量身打造的轻量级路由插件——uni-simple-router，它提供了类Vue Router的开发体验，同时保持了简洁高效的特性，让你的uni-app路由管理变得轻而易举。

读完本文，你将能够：

快速上手uni-simple-router的安装与配置
掌握路由定义、导航守卫、参数传递等核心功能
了解跨平台适配的最佳实践
通过实际案例学习如何在项目中应用

项目简介

uni-simple-router是一个专为uni-app打造的路由器插件，它与uni-app核心深度集成，让构建单页应用程序变得简单。作为一个轻量级解决方案，它不仅提供了丰富的路由功能，还保持了代码的简洁性和高性能。

项目基本信息：

项目名称：uni-simple-router
项目路径：gh_mirrors/un/uni-simple-router
项目描述：A simple, lightweight 'uni-app' routing plugin

核心特性一览：

特性	描述
类Vue Router API	熟悉的开发体验，降低学习成本
跨平台支持	完美适配H5、小程序和APP端
导航守卫	提供完整的路由拦截能力
路由参数	支持动态路由、查询参数等
轻量级	精简代码，不增加额外负担
模块化	基于组件的路由器配置

官方文档：README.md

快速开始

安装与配置

要在你的uni-app项目中使用uni-simple-router，首先需要通过npm安装：

npm install uni-simple-router --save

然后在项目中创建路由配置文件。以下是一个基本的路由配置示例：

// router.js
import { createRouter } from 'uni-simple-router';

const router = createRouter({
  platform: process.env.VUE_APP_PLATFORM,
  routes: [
    {
      path: '/',
      name: 'index',
      component: () => import('@/pages/index/index')
    },
    {
      path: '/login',
      name: 'login',
      component: () => import('@/pages/login/login')
    },
    // 更多路由配置...
    {
      path: '*',
      redirect: '/404'
    }
  ]
});

export default router;

在main.js中引入

创建好路由配置后，需要在main.js中引入并使用：

// main.js
import Vue from 'vue'
import App from './App'
import router from './router'

Vue.use(router)

App.mpType = 'app'

const app = new Vue({
  ...App
})

// H5端使用RouterMount
// #ifdef H5
RouterMount(app, router, '#app')
// #endif

// 非H5端使用$mount
// #ifndef H5
app.$mount();
// #endif

完整示例代码：examples/uni-simple-router2.0/main.js

核心功能详解

路由定义与配置

uni-simple-router支持多种路由定义方式，包括基本路由、动态路由、嵌套路由等。下面是一个更复杂的路由配置示例：

// router.js
export default createRouter({
  platform: process.env.VUE_APP_PLATFORM,
  routes: [
    {
      path: '/',
      name: 'index',
      component: () => import('@/pages/index/index')
    },
    {
      path: '/page2/:id',
      aliasPath: '/page2',
      name: 'page2',
      component: () => import('@/pages/page2/page2')
    },
    {
      path: '/:name/page3/:id',
      aliasPath: '/page3',
      name: 'page3',
      component: () => import('@/pages/page3/page3')
    },
    {
      path: '/dynamicPage',
      name: 'dynamicPage',
      component: () => import('@/pages/dynamicPage/dynamicPage')
    }
  ]
})

在pages.json中，你还可以配置页面的样式和其他属性：

{
  "pages": [
    {
      "path": "pages/index/index",
      "name": "index",
      "aliasPath": "/"
    },
    {
      "path": "pages/page2/page2",
      "aliasPath": "/page2/:id",
      "name": "page2"
    },
    {
      "path": "pages/page3/page3",
      "aliasPath": "/:name/page3/:id",
      "name": "page3"
    }
  ]
}

完整配置示例：examples/uni-simple-router2.0/pages.json

导航守卫

uni-simple-router提供了完整的导航守卫功能，包括全局守卫、路由独享守卫和组件内守卫。这让你可以在路由导航过程中实现各种控制逻辑，如登录验证、权限检查等。

下面是一个全局前置守卫的示例：

// router.js
router.beforeEach(async (to, from, next) => {
  // 检查是否需要登录
  if (to.meta.requiresAuth && !isLoggedIn()) {
    return next({ name: 'login', query: { redirect: to.fullPath } });
  }
  
  // 检查权限
  if (!hasPermission(to.meta.permission)) {
    return next({ name: '403' });
  }
  
  next();
});

router.afterEach((to, from) => {
  // 路由跳转完成后的操作，如修改页面标题
  document.title = to.meta.title || '默认标题';
});

在实际项目中，你可能需要更复杂的守卫逻辑。下面是一个来自示例项目的实际代码：

// router.js
let count = 0;
router.beforeEach(async (to, from, next) => {
  count++;
  await pageHookAnimation;
  next();
});

router.afterEach((to, from) => {
  console.log('afterEach---跳转结束');
});

完整代码：examples/uni-simple-router2.0/router.js

路由跳转与参数传递

uni-simple-router提供了多种路由跳转方式，包括编程式导航和声明式导航。

编程式导航

// 基本跳转
this.$Router.push({ path: '/page2' });

// 命名路由跳转
this.$Router.push({ name: 'page2', params: { id: 123 } });

// 带查询参数
this.$Router.push({ path: '/page2', query: { name: 'test' } });

// 替换当前页面
this.$Router.replace({ path: '/page2' });

// 返回上一页
this.$Router.back();

// 跳转到tabBar页面
this.$Router.pushTab({ path: '/tabbar/page' });

声明式导航

使用RouterLink组件进行声明式导航：

<template>
  <div>
    <router-link to="/page2">跳转到page2</router-link>
    <router-link :to="{ name: 'page3', params: { id: 123 } }">跳转到page3</router-link>
  </div>
</template>

在项目中注册RouterLink组件：

// main.js
import routerLink from './dist/link.vue'
Vue.component('RouterLink1', routerLink)

完整代码：examples/uni-simple-router2.0/main.js

跨平台适配

uni-simple-router的一大优势是其出色的跨平台适配能力。它为不同平台提供了针对性的配置选项：

const router = createRouter({
  platform: process.env.VUE_APP_PLATFORM,
  APP: {
    animation: {
      animationType: 'slide-in-top',
      animationDuration: 300
    },
    registerLoadingPage: true,
    loadingPageStyle: () => ({ backgroundColor: '#FFCCCC' }),
    loadingPageHook: async (view) => {
      // APP端加载页钩子
      view.show();
      // 显示加载动画
      const [, { screenWidth }] = await uni.getSystemInfo();
      view.drawBitmap('/static/wait3.gif', {}, {
        top: 'auto',
        left: 'auto',
        width: screenWidth + 'px',
        height: 'auto'
      });
      plus.navigator.closeSplashscreen();
      setTimeout(() => {
        pageHookAnimationEnd();
      }, 3500);
    }
  },
  applet: {
    animationDuration: 300
  },
  // 其他配置...
});

高级特性

动态路由

uni-simple-router支持动态路由匹配，允许你在路径中设置参数：

// 路由定义
{
  path: '/user/:id',
  name: 'user',
  component: () => import('@/pages/user/index')
}

// 路由跳转
this.$Router.push({ name: 'user', params: { id: 123 } });

// 在组件中获取参数
export default {
  onLoad() {
    console.log(this.$Route.params.id); // 123
  }
}

路由元信息

你可以在路由配置中添加元信息(meta字段)，用于存储路由相关的额外信息：

{
  path: '/admin',
  name: 'admin',
  component: () => import('@/pages/admin/index'),
  meta: {
    requiresAuth: true,
    permission: 'admin',
    title: '管理后台'
  }
}

然后在导航守卫中使用这些元信息：

router.beforeEach((to, from, next) => {
  // 检查是否需要登录
  if (to.meta.requiresAuth && !isLoggedIn()) {
    return next({ name: 'login' });
  }
  
  // 检查权限
  if (to.meta.permission && !hasPermission(to.meta.permission)) {
    return next({ name: '403' });
  }
  
  // 设置页面标题
  if (to.meta.title) {
    document.title = to.meta.title;
  }
  
  next();
});

错误处理

uni-simple-router提供了全局的路由错误处理机制：

const router = createRouter({
  // 其他配置...
  routerErrorEach: ({ type, level, ...args }) => {
    console.log({ type, level, ...args });
    
    // 处理特定类型的错误
    if (type === 3) {
      router.$lockStatus = false;
      // APP端特定处理
      // #ifdef APP-PLUS
      if (level == 1 && args.uniActualData.from === 'backbutton') {
        runtimeQuit();
      }
      // #endif
    } else if (type === 0) {
      router.$lockStatus = false;
    }
  }
});

实际应用案例

登录验证流程

下面是一个完整的登录验证流程实现，结合了导航守卫和路由元信息：

// router.js
router.beforeEach((to, from, next) => {
  // 检查是否需要登录
  if (to.meta.requiresAuth) {
    // 检查本地存储的登录状态
    const token = uni.getStorageSync('token');
    if (token) {
      // 已登录，检查权限
      if (checkPermission(to.meta.permission)) {
        next();
      } else {
        // 无权限，跳转到403页面
        next({ name: '403' });
      }
    } else {
      // 未登录，跳转到登录页面，并记录当前路径用于登录后返回
      next({ 
        name: 'login', 
        query: { redirect: to.fullPath } 
      });
    }
  } else {
    // 不需要登录的页面直接放行
    next();
  }
});

在登录页面，登录成功后跳转到之前记录的页面：

// login.vue
methods: {
  login() {
    // 登录逻辑...
    const token = '获取到的token';
    uni.setStorageSync('token', token);
    
    // 跳转到之前的页面，如果没有则跳转到首页
    const redirect = this.$Route.query.redirect || '/';
    this.$Router.push({ path: redirect });
  }
}

加载动画实现

在APP端，你可以自定义页面加载动画，提升用户体验：

// router.js
const router = createRouter({
  platform: process.env.VUE_APP_PLATFORM,
  APP: {
    registerLoadingPage: true,
    loadingPageStyle: () => JSON.parse('{"backgroundColor":"#FFCCCC"}'),
    loadingPageHook: async (view) => {
      console.log('------------loadingPageHook--------------');
      view.show();
      const [, { screenWidth }] = await uni.getSystemInfo();
      view.drawBitmap('/static/wait3.gif', {}, {
        top: 'auto',
        left: 'auto',
        width: screenWidth + 'px',
        height: 'auto'
      });
      plus.navigator.closeSplashscreen();
      setTimeout(() => {
        pageHookAnimationEnd();
      }, 3500);
    }
  }
});

完整代码：examples/uni-simple-router2.0/router.js

性能优化与最佳实践

路由懒加载

为了提高应用的初始加载速度，建议使用路由懒加载：

// 路由配置
{
  path: '/page2',
  name: 'page2',
  component: () => import('@/pages/page2/page2')
}

路由缓存

在uni-app中，可以通过配置pages.json来控制页面缓存：

{
  "pages": [
    {
      "path": "pages/index/index",
      "name": "index",
      "style": {
        "navigationBarTitleText": "首页",
        "enablePullDownRefresh": false,
        "app-plus": {
          "bounce": "none"
        }
      },
      "meta": {
        "keepAlive": true
      }
    }
  ]
}