准备工作
概述
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.request API 封装，提供统一的请求处理、错误处理和权限控制机制，支持 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进行对象深拷贝
配置说明
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
baseUrl |
string | H5: ${location.origin}/api/, 其他: VITE_APP_BASE_URL |
接口基础地址，从环境变量获取或使用默认值 |
showErrorMessage |
boolean | true |
是否显示错误消息 |
showSuccessMessage |
boolean | false |
是否显示成功消息 |
错误处理
错误码说明
| 错误码 | 说明 | 处理方式 |
|---|---|---|
| 0 | 业务错误 | 显示错误消息提示 |
| 400 | 请求参数错误 | 显示错误消息提示 |
| 401 | 未授权/登录过期 | 调用 useMemberStore().logout() 处理登出 |
| 402 | 站点已关闭 | 跳转到站点关闭页面 /app/pages/index/close |
| 403 | 站点不存在 | 跳转到站点不存在页面 /app/pages/index/nosite |
网络错误处理
系统自动处理以下网络错误：
-
请求成功但返回错误数据
-
请求失败
-
请求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 目录下，通过一键云端发布，系统会自动打包上传
