更新记录

1.0.0（2025-05-12） 下载此版本

v1.0.0 (2025-05-12)

• 初始版本发布，支持基本的路由拦截、白名单和登录检查功能
• 新增：支持自定义错误处理函数
• 优化：增强插件的容错能力，避免因配置错误导致应用崩溃
• 改进：添加版本信息输出，方便追踪插件版本

v1.0.0（2025-05-12） 下载此版本

v1.0.0 (2025-05-12)

• 初始版本发布，支持基本的路由拦截、白名单和登录检查功能
• 新增：支持自定义错误处理函数
• 优化：增强插件的容错能力，避免因配置错误导致应用崩溃
• 改进：添加版本信息输出，方便追踪插件版本

平台兼容性

hh-router-guard

一、插件简介

hh-router-guard 是一款专为 UniApp 框架设计的路由守卫插件，基于 Vue 3 构建。它提供了强大的页面访问权限控制、登录拦截和白名单功能，帮助开发者轻松管理应用的路由权限，提升应用安全性和用户体验。

通过简单配置，您可以：

• 拦截所有页面跳转请求，实现统一权限校验
• 强制未登录用户跳转至登录页面
• 灵活定义无需登录即可访问的白名单页面
• 自定义登录状态检查逻辑和错误处理机制

二、版本信息

• 当前版本：1.0.0
• 更新日期：2025-05-12
• 兼容性：支持所有 UniApp 支持的平台（微信小程序、H5、App、支付宝小程序等）

三、安装与引入

方式一：从 DCloud 插件市场下载

1. 访问 hh-router-guard 插件详情页
2. 点击「使用 HBuilderX 导入插件」按钮，将插件导入到您的项目中
3. 插件会自动被放置在项目的 uni_modules 目录下

方式二：手动导入

1. 下载插件源码压缩包
2. 将解压后的文件复制到项目的 uni_modules/hh-router-guard 目录

引入插件

在项目的 main.js 中引入并注册插件：

import { createSSRApp } from 'vue'
import App from './App.vue'
// 从 uni_modules 引入插件
import routerGuard from '@/uni_modules/hh-router-guard/src/index'

export function createApp() {
  const app = createSSRApp(App)

  // 安装路由守卫插件
  app.use(routerGuard, {
    // 配置选项
  })

  return { app }
}

四、快速上手

基础配置

以下是一个基础配置示例，展示如何设置白名单和登录检查逻辑：

app.use(routerGuard, {
  // 白名单：无需登录即可访问的页面路径
  whiteList: [
    '/pages/login/index',      // 登录页
    '/pages/public/*',         // 所有公共页面
    '/pages/about',            // 关于页
  ],

  // 自定义登录检查函数（返回 true 表示已登录）
  checkLogin: () => {
    const token = uni.getStorageSync('token')
    return !!token
  },

  // 登录页面路径
  loginPath: '/pages/login/index',

  // 未登录时的处理逻辑
  loginHandler: (to) => {
    uni.navigateTo({
      url: `${loginPath}?redirect=${encodeURIComponent(to)}`
    })
  }
})

完整配置选项

五、高级用法

自定义错误处理

您可以通过 errorHandler 选项自定义错误处理逻辑：

app.use(routerGuard, {
  // ...其他配置
  errorHandler: (error) => {
    uni.showToast({
      title: `路由错误: ${error.message}`,
      icon: 'none'
    })
  }
})

在组件中使用

插件会在 Vue 实例上挂载 $routerGuard 对象，您可以在组件中访问：

export default {
  methods: {
    checkPermission() {
      const isAllowed = this.$routerGuard.check('/pages/protected')
      console.log('当前用户是否有权限:', isAllowed)
    }
  }
}

六、示例项目

以下是一个完整的项目示例结构，展示如何集成和使用 hh-router-guard：

your-project/
├── pages/
│   ├── login/
│   │   └── index.vue         # 登录页面
│   ├── public/
│   │   ├── index.vue         # 公共页面
│   │   └── about.vue         # 关于页面
│   └── protected/
│       └── index.vue         # 需要登录才能访问的页面
├── uni_modules/
│   └── hh-router-guard/     # 插件目录
├── App.vue
└── main.js                   # 引入和配置插件的文件

七、更新日志

v1.0.0 (2025-05-12)

• 初始版本发布，支持基本的路由拦截、白名单和登录检查功能
• 新增：支持自定义错误处理函数
• 优化：增强插件的容错能力，避免因配置错误导致应用崩溃
• 改进：添加版本信息输出，方便追踪插件版本

八、常见问题

1. 如何解决 "routerGuard is not defined" 错误？

• 确保插件路径正确，特别是从 uni_modules 引入时
• 检查插件是否正确导出（使用 export default）
• 尝试重启 HBuilderX 清除缓存

2. 白名单路径支持哪些匹配模式？

• 完全匹配：如 /pages/login/index
• 前缀匹配：如 /pages/public/* 会匹配所有以 /pages/public/ 开头的路径

3. 如何在小程序和 H5 中使用不同的登录逻辑？

您可以在 checkLogin 函数中通过 uni.getSystemInfoSync().platform 判断运行环境，实现差异化逻辑：

checkLogin: () => {
  if (uni.getSystemInfoSync().platform === 'h5') {
    // H5 平台的登录检查逻辑
    return localStorage.getItem('token') !== null
  } else {
    // 小程序平台的登录检查逻辑
    return uni.getStorageSync('token') !== ''
  }
}

九、贡献与反馈

如果您在使用过程中遇到问题或有任何建议，欢迎：

• 在 插件市场评论区 留言反馈
• 提交 Issues 到 Github 仓库
• 提交 Pull Requests 参与开发

十、许可证

本插件采用 MIT 许可证 发布，您可以自由使用、修改和分发。