# 【RuoYi-SpringBoot3-UniApp】：一套代码，多端运行的移动端开发方案

## 一、项目简介

[RuoYi-SpringBoot3-UniApp](https://github.com/undsky/RuoYi-SpringBoot3-UniApp) 是基于 UniApp 开发的跨平台移动端项目，一套代码可同时发布到微信小程序、App（Android/iOS）、H5 和桌面端，显著降低开发成本和维护难度。

**核心特点：**
- ✅ 一套代码，多端运行（小程序、App、H5、桌面端）
- ✅ 基于 Vue3 组合式 API，代码更简洁
- ✅ 内置完整认证体系和权限管理
- ✅ 集成主流 UI 组件库（uni-ui）
- ✅ 支持 Electron 打包为桌面应用

## 二、核心功能特性

### 3.1 完整的认证体系

**JWT Token 认证流程：**

```javascript
// 1. 登录获取 Token
login(username, password) 
  → 后端返回 Token 
  → 存储到本地

// 2. 请求自动携带 Token
request(url) 
  → 拦截器添加 Token 到 Header 
  → 发送请求

// 3. Token 失效处理
Token 过期 
  → 拦截器检测 401 
  → 自动跳转登录页
```

**核心特性：**
- ✅ 记住密码（下次自动登录）
- ✅ RSA 加密传输（密码不明文）
- ✅ 路由拦截（未登录自动跳转）
- ✅ 白名单机制（部分页面无需登录）

### 3.2 路由守卫 —— 权限控制核心

```javascript
// permission.js
const loginPage = "/pages/login"

// 白名单：这些页面无需登录
const whiteList = [
  '/pages/login',      // 登录页
  '/pages/register',   // 注册页
  '/pages/common/webview/index'  // 网页浏览
]

// 页面跳转时自动拦截
uni.addInterceptor('navigateTo', {
  invoke(e) {
    const token = getToken()
    
    // 没有 Token 且不在白名单 → 跳转登录
    if (!token && !whiteList.includes(e.url)) {
      uni.navigateTo({ url: loginPage })
      return false
    }
    
    return true
  }
})
```

**实现效果：**
- 用户未登录访问"我的"页面 → 自动跳转登录页
- 登录成功后 → 自动跳转回原页面
- 退出登录 → 清除 Token，跳转登录页

### 3.3 Pinia 状态管理 —— 告别混乱

**为什么需要状态管理？**

没有状态管理时：
```
组件 A 修改用户信息 
→ 需要通过事件通知组件 B 
→ 再通知组件 C 
→ 代码混乱，难以维护
```

有状态管理后：
```
组件 A 修改 Store 中的用户信息 
→ 所有组件自动更新 
→ 代码清晰，易于维护
```

**实际代码：**

```javascript
// store/modules/user.js
import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
  state: () => ({
    token: '',
    userInfo: {}
  }),
  
  actions: {
    // 登录
    login(username, password) {
      return loginApi(username, password).then(res => {
        this.token = res.token
        this.userInfo = res.user
      })
    },
    
    // 退出
    logout() {
      this.token = ''
      this.userInfo = {}
      removeToken()
    }
  }
})
```

**在组件中使用：**

```vue
<template>
  <view>{{ userStore.userInfo.nickName }}</view>
  <button @click="handleLogout">退出登录</button>
</template>

<script setup>
import { useUserStore } from '@/store/modules/user'

const userStore = useUserStore()

const handleLogout = () => {
  userStore.logout()
  uni.navigateTo({ url: '/pages/login' })
}
</script>
```

## 四、实用插件生态

### 4.1 z-paging —— 列表分页终极方案

**痛点：** 传统列表开发需要手动处理：
- 下拉刷新逻辑
- 上拉加载更多
- 加载状态管理
- 空数据提示
- 网络错误处理

**解决方案：** z-paging 一站式解决。

```vue
<template>
  <z-paging 
    ref="paging" 
    v-model="dataList" 
    @query="queryList"
  >
    
    <view v-for="item in dataList" :key="item.id">
      <text>{{ item.name }}</text>
    </view>
  </z-paging>
</template>

<script setup>
import { ref } from 'vue'
import { getUserList } from '@/api/system/user'

const paging = ref(null)
const dataList = ref([])

// 查询列表（分页自动处理）
const queryList = (pageNo, pageSize) => {
  getUserList({ pageNo, pageSize }).then(res => {
    // 告诉 z-paging 数据加载完成
    paging.value.complete(res.rows)
  })
}
</script>
```

**效果：**
- ✅ 首次加载显示 loading
- ✅ 下拉刷新自动重置页码
- ✅ 上拉加载更多自动翻页
- ✅ 没有更多数据自动提示
- ✅ 加载失败自动显示错误

### 4.2 mp-html —— 富文本渲染神器

**跨平台难题：** 不同平台的富文本渲染能力差异巨大。

| 平台 | 原生支持 | 问题 |
|------|---------|------|
| H5 | `<div v-html>` | 简单但不安全 |
| 微信小程序 | `<rich-text>` | 功能有限 |
| App | 无原生支持 | 需要 WebView |

**mp-html 统一方案：**

```vue
<template>
  
  <mp-html :content="htmlContent" />
</template>

<script setup>
import { ref } from 'vue'

const htmlContent = ref(`
  <h1>标题</h1>
  <p>段落文本</p>
  <img src="xxx.jpg" />
  <table>...</table>
`)
</script>
```

**核心优势：**
- ✅ 所有平台统一渲染效果
- ✅ 支持 HTML 标签和 CSS
- ✅ 支持图片懒加载
- ✅ 支持视频播放
- ✅ 自动适配屏幕宽度

### 4.3 uni-ui —— 官方组件库

50+ 精选组件，覆盖常见场景：

```vue
<template>
  
  <uni-forms :model="form">
    <uni-forms-item label="用户名">
      <uni-easyinput v-model="form.username" />
    </uni-forms-item>
  </uni-forms>
  
  
  <uni-list>
    <uni-list-item title="标题" note="描述" />
  </uni-list>
  
  
  <uni-popup ref="popup">
    <view>弹窗内容</view>
  </uni-popup>
  
  
  <uni-calendar @change="onChange" />
</template>
```

## 五、条件编译 —— 跨平台兼容的利器

**问题：** 不同平台有不同的 API 和表现。

**解决方案：** UniApp 的条件编译机制。

### 5.1 模板条件编译

```vue
<template>
  
  
  <button open-type="getUserInfo">授权登录</button>
  
  
  
  
  <input type="text" placeholder="请输入账号" />
  
  
  
  
  <view @click="scanCode">扫码登录</view>
  
  
  
  
  <view>通用登录方式</view>
  
</template>
```

### 5.2 JavaScript 条件编译

```javascript
<script>
// 微信小程序特有逻辑
// #ifdef MP-WEIXIN
const login = () => {
  wx.login({
    success: res => console.log(res.code)
  })
}
// #endif

// H5 特有逻辑
// #ifdef H5
const login = () => {
  window.location.href = '/oauth/login'
}
// #endif

// App 特有逻辑
// #ifdef APP-PLUS
const login = () => {
  plus.oauth.getServices(services => {
    // 调用原生登录
  })
}
// #endif
</script>
```

### 5.3 样式条件编译

```css
<style>
/* 微信小程序 */
/* #ifdef MP-WEIXIN */
.title {
  font-size: 28rpx;
  color: #07c160; /* 微信绿 */
}
/* #endif */

/* H5 */
/* #ifdef H5 */
.title {
  font-size: 16px;
  color: #409eff; /* Element Blue */
}
/* #endif */
</style>
```

## 六、Electron 桌面端 —— 锦上添花

### 为什么需要桌面端？

**场景：** 企业内部管理系统，员工希望有独立的桌面应用，不想每次都打开浏览器输入网址。

**方案：** 将 UniApp H5 打包成桌面应用。

### 使用步骤

```bash
# 1. 构建 H5 版本
npm run build:h5

# 2. 进入 electron 目录
cd electron

# 3. 安装依赖
npm install

# 4. 开发模式（加载本地服务）
npm run dev

# 5. 生产模式（加载打包后的 H5）
npm run prod
```

### 核心配置

```javascript
// electron/main.js
const { app, BrowserWindow } = require('electron')

app.whenReady().then(() => {
  const win = new BrowserWindow({
    width: 1200,
    height: 800,
    webPreferences: {
      nodeIntegration: true
    }
  })
  
  // 开发模式：加载本地服务
  if (process.env.NODE_ENV === 'development') {
    win.loadURL('http://localhost:5173')
  } 
  // 生产模式：加载打包的 H5 文件
  else {
    win.loadFile('../dist/index.html')
  }
})
```

**优势：**
- ✅ 支持 Windows、macOS、Linux
- ✅ 原生窗口体验（有菜单、图标、快捷键）
- ✅ 可调用 Node.js 能力（文件操作、系统通知等）
- ✅ 开发调试方便（内置开发者工具）

## 七、快速开始

### 7.1 环境准备

```bash
# 必需
Node.js 20+
HBuilderX（UniApp 官方 IDE）

# 可选（根据目标平台）
微信开发者工具（开发小程序）
Android Studio（开发 Android App）
Xcode（开发 iOS App，仅 macOS）
```

### 7.2 三步启动

**第一步：克隆并安装**
```bash
git clone https://github.com/undsky/RuoYi-SpringBoot3-UniApp.git
cd RuoYi-SpringBoot3-UniApp
npm install
```

**第二步：配置后端地址**
```javascript
// config.js
export default {
  baseUrl: 'http://localhost:8087',  // 修改为你的后端地址
}
```

**第三步：运行项目**
1. 用 HBuilderX 打开项目
2. 点击"运行" → 选择平台：
   - 运行到浏览器（H5）
   - 运行到小程序模拟器
   - 运行到手机或模拟器（App）

**访问系统：**
- H5：`http://localhost:5173`
- 小程序：在微信开发者工具中预览
- App：在模拟器或真机中查看

## 八、项目结构

```
RuoYi-SpringBoot3-UniApp/
├── api/                    # API 接口
│   ├── login.js           # 登录接口
│   └── system/            # 系统模块接口
├── components/             # 全局组件
├── electron/               # Electron 桌面应用
│   ├── main.js            # 主进程
│   └── package.json       # 依赖配置
├── pages/                  # 页面目录
│   ├── index.vue          # 首页
│   ├── login.vue          # 登录页
│   ├── work/              # 工作台模块
│   └── mine/              # 个人中心模块
├── plugins/                # 插件封装
│   ├── auth.js            # 权限插件
│   ├── modal.js           # 消息提示
│   └── tab.js             # 标签页管理
├── store/                  # 状态管理（Pinia）
│   ├── index.js           # Store 入口
│   └── modules/           # Store 模块
├── uni_modules/            # UniApp 插件
│   ├── uni-ui/            # UI 组件库
│   ├── z-paging/          # 分页组件
│   └── mp-html/           # 富文本组件
├── utils/                  # 工具库
│   ├── request.js         # 请求封装
│   ├── auth.js            # 认证工具
│   └── storage.js         # 存储工具
├── App.vue                 # 应用入口
├── main.js                 # 入口文件
├── pages.json              # 页面路由配置
├── manifest.json           # 应用配置
├── permission.js           # 路由守卫
└── config.js               # 全局配置
```

## 十一、总结

RuoYi-SpringBoot3-UniApp 是一个**生产就绪**的跨平台移动端解决方案。

**核心优势：**

1. **真正的跨平台**
   - 一套代码，5 个平台
   - 开发成本降低 70%
   - 维护更简单

2. **现代化技术栈**
   - Vue 3 组合式 API
   - Pinia 状态管理
   - TypeScript 支持（可选）

3. **完善的功能**
   - 认证体系（JWT + RSA）
   - 路由守卫（权限控制）
   - 状态管理（Pinia）

4. **丰富的插件**
   - z-paging（分页方案）
   - mp-html（富文本）
   - uni-ui（50+ 组件）

5. **开箱即用**
   - 登录注册
   - 个人中心
   - 工作台
   - 权限管理

---

+ 项目地址：[RuoYi-SpringBoot3-UniApp](https://github.com/undsky/RuoYi-SpringBoot3-UniApp)
+ 开发文档：[RuoYi-SpringBoot3-Pro 文档](https://www.undsky.com/blog/?category=RuoYi-SpringBoot3-Pro#)

RuoYi-SpringBoot3-UniApp 是基于 UniApp 开发的跨平台移动端项目，一套代码可同时发布到微信小程序、App（Android/iOS）、H5 和桌面端，显著降低开发成本和维护难度。

【RuoYi-SpringBoot3-UniApp】：一套代码，多端运行的移动端开发方案

开发工具

RuoYi-SpringBoot3-UniApp是一套基于Vue3+UniApp的跨平台移动端开发方案，支持微信小程序、App、H5和桌面端多端运行。内置JWT认证、权限管理、Pinia状态管理等核心功能，集成uni-ui、z-paging等实用组件，提供Electron桌面端打包方案。一套代码即可实现多平台适配，显著降低开发维护成本，是企业级移动开发的理想选择。

TypeScript

Android

Windows

路由

Linux

Xcode

AI驱动 智领未来

coding

文章

问答

视频

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

RuoYi-SpringBoot3-UniApp是一套基于Vue3+UniApp的跨平台移动端开发方案，支持微信小程序、App、H5和桌面端多端运行。内置JWT认证、权限管理、Pinia状态管理等核心功能，集成uni-ui、z-paging等实用组件，提供Electron桌面端打包方案。一套代码即可实现多平台适配，显著...

【RuoYi-SpringBoot3-UniApp】：一套代码，多端运行的移动端开发方案-腾讯云开发者社区-腾讯云

【RuoYi-SpringBoot3-UniApp】：一套代码，多端运行的移动端开发方案

【RuoYi-SpringBoot3-UniApp】：一套代码，多端运行的移动端开发方案

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐