1. 移动端简介与环境搭建

移动端手册环境搭建大约 5 分钟约 1474 字

一句话定位

App/ 是一个 uni-app + Vue3 工程，一套代码编译到 H5 / 微信小程序 / Android / iOS，通过 /api/** 直连 Admin.NET 后端（http://localhost:5005）。

工程全景

Admin.NET.Pro_v2.1
├─ Admin.NET/                       # 后端 .NET 解决方案
│  ├─ Admin.NET.Application/Service/App/Auth/
│  │  ├─ AppAuthService.cs          # 移动端专用认证服务  /api/appAuth/**
│  │  └─ AppUserManager.cs          # 继承自 UserManager，可扩展移动端属性
│  └─ Admin.NET.Web.Entry/          # 启动项，默认 http://localhost:5005
└─ App/                             # 移动端 uni-app 工程（本文主角）
   ├─ App.vue                       # 应用生命周期 + 全局 page 样式
   ├─ main.js                       # createApp：初始化 request / 权限指令
   ├─ pages.json                    # 页面路由、globalStyle、tabBar、easycom
   ├─ manifest.json                 # 应用标识、各端配置（appid、权限、图标）
   ├─ index.html                    # H5 模板
   ├─ uni.scss                      # 全局 SCSS 变量（$uni-color-primary 等）
   ├─ tsconfig.json                 # @/* 路径别名
   ├─ package.json                  # 运行期依赖（sm-crypto / base-64 / dayjs / jsbn）
   ├─ androidPrivacy.json           # Android 隐私政策弹窗（"prompt":"template"）
   ├─ uni.promisify.adaptor.js      # uni API Promise 化适配器
   ├─ api/base/                     # 接口封装基类（index.ts / request.ts）
   ├─ api_all/                      # 由后端生成的接口契约（appAuth/sysAuth/sysCommon/sysLogOp/appH5Demo）
   ├─ pages/                        # 页面：login / home / mine / password / about / feedback
   │  └─ component/                 # 可复用组件：tabbar / sysLogOp / BusinessOverview / OrderOverview
   ├─ static/                       # 静态资源：bg.jpg / logo.png / swiper / tabIcon
   ├─ utils/                        # .env.js / http.js / request.js / authFunction.ts / encrypt.js / validate.js / getUrlParam.js
   └─ .hbuilderx/launch.json        # HBuilderX 调试配置（uniCloud local/remote）

一、技术栈与关键版本

项	值	来源
框架	uni-app（Vue 3）	`manifest.json` → `"vueVersion": "3"`
应用标识	`__UNI__B91D75F`	`manifest.json` → `"appid"`
版本	versionName `1.0.0` / versionCode `100`	`manifest.json`
语言	`zh-Hans`	`manifest.json` → `locale`
主色	`#11559c`	`uni.scss` → `$uni-color-primary`
后端地址	`http://localhost:5005`	`utils/.env.js` → `baseUrl`
密码加密	国密 SM2（`sm-crypto`）	`utils/.env.js` → `smKey`

二、依赖与运行脚本

App/package.json 现状（仓库真实内容，未含 scripts 与 devDependencies）：

{
  "dependencies": {
    "base-64": "^1.0.0",     // utils/request.js 解密 JWT
    "dayjs": "^1.11.13",     // 时间处理
    "jsbn": "^1.1.0",        // sm-crypto 依赖
    "sm-crypto": "^0.3.13"   // 登录/改密密码 SM2 加密：sm2.doEncrypt(pwd, key, 1)
  }
}

CLI 方式需要自行补齐

仓库未提供 scripts 与 @dcloudio/* 编译依赖。若要用命令行运行，需先补充 package.json（示例见下），再 npm install。推荐直接用 HBuilderX，可跳过这一步。

// 仅作 CLI 方式参考，本仓库未内置
{
  "scripts": {
    "dev:h5": "uni",
    "build:h5": "uni build",
    "dev:mp-weixin": "uni -p mp-weixin",
    "build:mp-weixin": "uni build -p mp-weixin"
  },
  "devDependencies": {
    "@dcloudio/uni-cli-shared": "*",
    "@dcloudio/vite-plugin-uni": "*",
    "vite": "*"
  }
}

三、启动方式一：HBuilderX（推荐）

安装 HBuilderX（App 开发版）。
菜单 文件 → 导入 → 从本地目录导入，选择 App/ 整个目录。
首次运行前，确认 manifest.json 中 mp-weixin.appid 已填（小程序端），基础配置 中的应用标识自动生成。
运行：
- H5：运行 → 运行到浏览器 → Chrome
- 小程序：运行 → 运行到小程序模拟器 → 微信开发者工具（需先开启工具的服务端口）
- App：运行 → 运行到手机或模拟器 → 安卓/iOS
调试断点配置在 .hbuilderx/launch.json（当前仅有 launchtype: local 的 uniCloud 节点）。

四、启动方式二：CLI

cd App
npm install                      # 安装上面补齐的依赖
npm run dev:h5                   # H5 开发
npm run dev:mp-weixin            # 微信小程序，产物在 dist/dev/mp-weixin
# 用微信开发者工具打开 dist/dev/mp-weixin 目录即可预览

五、后端联调地址配置

App/utils/.env.js 是唯一的后端地址开关（提交代码前请改成你的实际环境）：

const env = {
  baseUrl: 'http://localhost:5005', // 服务器地址
  header: {},                       // 全局请求头（initRequest 会写入 token）
  smKey: "04851D329AA3E38C2E7670AFE70E6E70E92F8769CA27C8766B12209A0FFBA4493B603EF7A0B9B1E16F0E8930C0406EA0B179B68DF28E25334BDEC4AE76D907E9E9", // SM2 国密公匙（与后端 CryptogramHelper 配对）
  defaultUser: 'superAdmin.NET',    // 登录页默认账号
  defaultPassword: 'Admin.NET++010101',
  defaultServicePhone: '18012345678'
}
export { env }

后端地址来源：Admin.NET.Web.Entry/Properties/launchSettings.json → applicationUrl: http://localhost:5005。接口默认是 /api/** 前缀（Furion 动态 API DefaultRoutePrefix，配置注释里默认为 api）。

# 启动后端（两种皆可）
dotnet run --project Admin.NET/Admin.NET.Web.Entry
# 或在 Visual Studio 选择 Admin.NET.Web.Entry 启动（IIS Express / 项目 都是 5005 端口）

六、运行到不同端的差异

维度	H5	微信小程序	App（Android/iOS）
入口文件	`index.html`	无（`app.js` 由编译生成）	无
跨域	有，需后端 CORS 或 nginx 反向代理	无（但域名必须在白名单且 https）	无
地址要求	可 http://localhost	必须 https + 备案域名	可 http/https
组件编译	标准 Vue 组件	受小程序标签限制（`div/span` 不推荐）	同小程序约束
本地存储	localStorage（uni 统一封装）	`wx.setStorageSync`	原生存储
上传	`uni.uploadFile` / FormData 可用	FormData 不可用，必须 `uni.uploadFile`	必须 `uni.uploadFile`
主配置	`manifest.json` 的 h5 节点	`mp-weixin.appid`	`app-plus.distribute`（权限/图标）
隐私合规	—	需在小程序后台配置	`androidPrivacy.json`（当前 `prompt: template`）

步骤清单

拉起后端：dotnet run --project Admin.NET/Admin.NET.Web.Entry，确认 http://localhost:5005/swagger 可访问。
核对 App/utils/.env.js 的 baseUrl、smKey 与后端一致。
HBuilderX 导入 App/ 目录（或 CLI 补齐 package.json 后 npm install）。
H5 先跑通：运行到浏览器，登录页应能看到验证码，用默认账号登录。
再切微信小程序：填 manifest.json → mp-weixin.appid，用微信开发者工具打开编译产物。
最后打 App：manifest.json → app-plus 配置图标与权限，androidPrivacy.json 确认合规弹窗。

⚠️ 注意事项与常见坑

baseUrl 不要带尾斜杠：api/base/index.ts 拼接规则是 /api/${module}/ + 动作名，多一个 / 会出现 //api。
小程序端 http://localhost 连不通：真机预览必须 https 域名；开发时可在微信开发者工具勾选「不校验合法域名」，manifest.json 的 mp-weixin.setting.urlCheck 已是 false。
H5 跨域报 CORS：用 nginx 把 /api 反代到后端，或直接让后端开启 CORS，不要在生产用 * 通配凭证请求。
utils/api 目录里没有 node_modules：仓库未提交依赖，切换机器务必 npm install。
首页是登录页：pages.json 中 pages 数组第一项为 pages/login/login，想改启动页就调整数组顺序。
删除了 uview-plus：uni.scss 顶部注明 base theme removed uview-plus import，示例代码里的 /static/uview/swiper/swiper2.png 等路径在仓库中不存在，需自行替换（真实资源在 /static/swiper/）。

小结

移动端就是「一个 uni-app 工程 + 一个 .env.js 地址开关」。把后端跑在 5005、把 baseUrl 指过去、用 HBuilderX 打开 App/，即可登录进入首页；后续各端差异只在 manifest.json 与发布环节。