基于Vue 3和UniApp的跨平台移动应用开发模板

Question

vue-uniapp-template 移动端

项目简介
vue-uniapp-template 是一个基于 Vue 3 和 UniApp 构建的跨平台移动应用模板。其核心理念是“一套代码，多端编译”，开发者可以使用同一套代码基础，同时发布到 H5、各类小程序以及原生 App 等多个平台。

项目特色

📱 跨平台支持

该模板广泛支持当前主流移动端平台：

H5：适用于浏览器及微信公众号等Web环境。
小程序：支持微信、支付宝、百度、字节跳动等平台的小程序。
App：可编译为 Android 与 iOS 原生应用。
快应用：兼容华为、小米等厂商的快应用平台。

🎨 UI 组件与设计

在UI层面，模板提供了丰富的解决方案：

集成 wot-design-uni 组件库，这是一个基于 Wot Design 规范的高质量组件库，包含超过70个常用组件。
支持自定义业务组件开发。
采用响应式设计，确保在不同屏幕尺寸上均有良好表现。
内置暗黑模式支持，可实现深色主题切换。
提供国际化（多语言）支持与灵活的自定义主题能力。

⚡ 开发体验

模板采用现代前端技术栈以优化开发体验：

使用 Vue 3 Composition API 进行开发。
支持 TypeScript 以获得类型安全（可选）。
兼容官方 IDE HBuilderX，并支持热重载功能，实现开发效果的实时预览。

技术栈

模板所采用的核心技术及版本如下：

Vue：3.x，作为渐进式前端框架。
Vite：5.x，用于项目构建。
TypeScript：5.x，提供类型安全。
UniApp：3.x，实现跨平台能力的核心框架。
wot-design-uni：1.x，UI 组件库（含70+组件）。
Pinia：2.x，用于状态管理。
UnoCSS：原子化 CSS 引擎。
uni-request：封装的网络请求库。

快速开始

环境准备

在开始之前，请确保你的开发环境满足以下要求：

Node.js：版本需要在 16 及以上。
开发工具：推荐安装 HBuilderX，这是 UniApp 的官方 IDE。你也可以选择使用 Vue CLI。

项目启动

你可以通过以下两种方式启动项目：

使用 HBuilderX：

打开 HBuilderX。
通过菜单 文件 -> 导入 -> 从本地目录导入 来导入项目。
选择项目所在的目录。
在顶部菜单选择 运行，然后选择要运行到的目标（浏览器、模拟器或真机）。

使用命令行：

# 克隆项目仓库
git clone https://gitee.com/youlaiorg/vue-uniapp-template.git

# 进入项目目录
cd vue-uniapp-template

# 安装项目依赖
npm install

# 启动 H5 开发环境
npm run dev:h5

# 启动微信小程序开发环境
npm run dev:mp-weixin

# 启动 App 开发环境
npm run dev:app

接口配置

项目的接口配置位于 src/config/config.js 文件中，你需要根据实际情况修改开发环境和生产环境的 API 地址等参数。

项目结构

项目采用清晰的分层目录结构，便于维护：

vue-uniapp-template
├── pages                 # 所有页面文件目录
├── components           # 组件目录（含公共组件和业务组件）
├── static               # 静态资源（如图片、图标）
├── store                # Pinia 状态管理目录
├── utils                # 工具函数目录（如请求封装、认证工具）
├── uni_modules          # 官方或第三方 uni 插件
├── App.vue              # 应用根组件和全局配置
├── main.js              # 应用入口文件
├── manifest.json        # 应用配置文件
└── pages.json           # 页面路由与窗口样式配置文件

核心功能

用户登录

模板提供了完整的登录页面示例，使用 wot-design-uni 组件构建表单，并通过 Pinia 状态管理库处理登录逻辑。登录成功后，会进行页面跳转并提示用户。

网络请求

项目在 utils/request.js 中对 uni.request API 进行了统一封装。该封装自动拼接基础URL、设置请求头（如携带认证Token），并统一处理成功与失败的响应，简化了业务代码中的调用。

状态管理

使用 Pinia 进行全局状态管理。例如，用户模块的 Store 负责管理用户令牌（Token）和用户信息，并提供了登录、获取用户信息、登出等异步操作，且状态会与本地存储同步。

平台差异处理

条件编译

UniApp 提供了条件编译语法，以处理不同平台间的代码差异。你可以在模板、样式或脚本中使用和注释来包裹特定平台才需要编译的代码。

API 差异

虽然 UniApp 的 API 是统一的，但部分 API 仅在特定平台有效。例如，获取系统信息、导航跳转、显示提示等 API 在所有平台通用，而像 uni.requestPermission（申请权限）这类 API 通常仅在 App 平台可用。对于此类平台特定的 API，建议配合条件编译使用。

常用组件示例

列表展示

模板展示了如何使用 u-list 和 u-list-item 组件实现一个支持上拉加载更多的长列表。当列表滚动到底部时，会触发 scrolltolower 事件来加载下一页数据。

图片上传

通过 u-upload 组件可以方便地实现图片上传功能。该组件支持预览、删除，并在用户选择图片后通过 uni.uploadFile API 将文件上传至服务器。

打包发布

H5 打包：运行构建命令后，生成的文件位于 dist/build/h5 目录，可直接部署到 Web 服务器。
小程序打包：执行对应的构建命令（如 npm run build:mp-weixin），生成目录 dist/build/mp-weixin，然后使用各平台官方开发者工具打开并上传代码。
App 打包：推荐使用 HBuilderX 进行云打包。在菜单中选择 发行 -> 原生 App-云打包，然后根据向导选择平台、配置证书与图标等选项即可生成安装包。