准备工作​

概述​

uni-app 是一个使用 Vue.js 开发所有前端应用的框架，支持同时生成 ios、Android、H5、以及各种小程序等多平台应用。本项目基于 Vue 3、Vite 和 TypeScript 构建，集成了 Pinia 状态管理、uview-plus UI 组件库和 WindiCSS 样式框架

开发环境搭建​

工具​

• Node.js

• HBuilderX（可选）：uni-app 官方推荐的 IDE，提供完整的开发工具链支持

环境配置步骤​

1.安装 Node.js：

访问 Node.js 官网 下载并安装最新稳定版

2.安装 HBuilderX：

访问 HBuilderX 官网 下载并安装，建议选择标准版或 App 开发版

3.安装依赖：

在项目根目录下运行以下命令：

bash

npm install

开发工作流​

开发调试​

H5 开发：

bash

npm run dev:h5 #在浏览器中预览

小程序开发：

bash

npm run dev:mp-weixin #在微信开发者工具中预览

构建发布​

• H5构建：npm run build:h5，生成H5应用包

• 小程序构建：npm run build:mp-weixin，生成小程序代码包

• App构建：使用HBuilderX的发行功能，生成Android/iOS应用包

相关文档链接​

• uni-app 官方文档：uni-app官网

• Vue 3 官方文档：Vue.js - The Progressive JavaScript Framework | Vue.js

• Pinia 官方文档：Pinia | The intuitive store for Vue.js

• WindiCSS 官方文档：Windi CSS

目录结构​

路由​

路由配置概述​

pages.json 是项目的核心路由配置文件，位于 uni-app/src/ 目录下。该文件定义了应用的所有页面、全局样式、选项卡栏等配置信息

路由配置详解​

页面配置（pages）​

pages 数组是路由配置的核心，定义了应用中所有的页面路径和样式。数组中的第一项表示应用的启动页

基本结构：

json

"pages": [ { "path": "页面路径", "style": { "navigationBarTitleText": "页面标题", "navigationStyle": "导航栏样式", // 其他样式配置 }, "needLogin": true // 是否需要登录 } // 更多页面配置 ]

分包配置（subPackages）​

项目使用了分包加载机制，将部分页面打包到不同的子包中，按需加载，以优化应用性能

配置示例：

json

"subPackages": [ { "root": "app/components", "pages": [] }, { "root": "app/pages/member", "pages": [ // 会员相关页面配置 ] } ]

接口​

接口概述​

uni-app 端接口系统基于uni.requestAPI 封装，提供统一的请求处理、错误处理和权限控制机制，支持 H5、小程序、App 等多端运行环境。所有接口通过request.ts工具类进行统一管理，使用qs库进行参数序列化，确保接口调用的一致性和可维护性

API 请求配置​

请求工具类封装​

request.ts是 uni-app 端的核心请求工具类，封装了请求拦截、响应处理、错误处理等功能。文件位置：uni-app/src/utils/request.ts

核心功能​

• 请求拦截器：自动携带token、app-channel等请求头信息

• 响应处理：统一处理响应数据，支持成功/错误消息提示

• 错误处理：统一处理网络错误、业务错误和认证错误

• 多端适配：支持 H5、小程序、App 等多端环境

• 文件上传：封装uni.uploadFileAPI，支持图片、视频等文件上传

• 参数序列化：使用qs库进行参数序列化

• 对象深拷贝：使用uni.$u.deepClone进行对象深拷贝

配置说明​

错误处理​

错误码说明​

网络错误处理​

系统自动处理以下网络错误：

• 请求成功但返回错误数据

• 请求失败

• 请求URL不在域名列表中

文件上传错误处理​

文件上传错误处理与普通请求错误处理逻辑一致，支持显示错误消息和跳转到相应页面

手机端 h5 编译上传​

安装依赖​

首先需要安装依赖，将文件切换到根目录下的 uniapp 下，cmd 启动命令行，再输入 npm install 执行安装依赖

编译打包​

将文件切换到根目录下的 uniapp 下，cmd 启动命令行。执行命令 npm run build:h5 进行打包编译

完成编译后在根目录下的 uniapp 目录下会生成 dist 文件夹

将编译文件打包压缩，如下图所示：

将刚刚压缩的编译包上传到 webroot/public/wap 目录下，这样就完成了手机端的编译上传。这个时候访问手机端链接就可以看到页面内容

微信小程序端编译上传​

安装依赖​

打开源码所在目录，将路径打开到 uniapp 下，如图：

安装完依赖之后，会看到在 uniapp 文件夹下会生成一个 node_modules 文件夹。如图：

命令行编译上传​

方式一​

在 uniapp 目录下打开终端，执行 npm run build:mp-weixin 进行编译，如图：

编译完成后，在 uni-app/dist/build 下会生成编译文件夹 mp_weixin

点击开发者工具右上角的上传，即可将小程序发布线上审核，上传完成后，登录小程序开发者平台，将提交的项目点击审核，审核通过后，再通过小程序开发者平布点击发布，这样小程序就上线了

方式二​

将修改后的源码放到至 webroot/runtime/uni-app/src 目录下，通过一键云端发布，系统会自动打包上传