更新记录

1.0.0（2026-08-13） 下载此版本

uniappx 基础脚手架，包含功能： 1.基础简单的登录示例代码 2.request请求封装 3.跳转 + 登录白名单/拦截 4.版本更新(多渠道，应用市场， 蒲公英分发或第三方链接等平台) 5.文件的上传下载 6.图像裁剪上传封装 7.主题的切换，包括明暗主题与自定义主题等

平台兼容性

uni-app x(5.24)

其他

base_uniappx 多端基础脚手架

基于 uni-app x 官方规范（uvue + script setup lang="uts"）的多端起步模板。

官方文档：uvue · UTS · downloadFile · uploadFile · installApk · chooseImage

能力一览

目录结构

api/           # user / update
components/    # scaffold-empty、scaffold-avatar、scaffold-color-picker
config/        # env、update、theme
constants/
pages/
  index/ login/ demo/ profile/ theme/custom common/webview
store/         # user、app、theme
utils/         # request、storage、router、update、file-transfer、avatar、open-link、color…

外链说明（重要）

当前 uni-app x 内置无 uni.openURL。脚手架默认：

• http(s) → 打开 pages/common/webview
• market:// / itms-apps:// 等 → 复制到剪贴板并 Toast

若要系统浏览器 / 直接拉起商店，请安装插件 uts-openSchema，在 utils/open-link.uts 的 openBySchemaPlugin 中调用 openSchema(url)。

1. 配置 config/update.uts

• androidPackage / iosAppStoreId / harmonyStoreUrl
• pgyerUrl：蒲公英安装页
• thirdPartyUrl：任意下载说明页
• defaultChannel：store | pgyer | url | apk
• autoCheckOnLaunch：启动自动检查（默认 false）

2. 业务调用（UTS 禁止传函数引用）

import { fetchUpdateInfo } from '@/api/update.uts'
import { checkAndPromptUpdate, openUpdateChannel } from '@/utils/update.uts'

const info = await fetchUpdateInfo()
await checkAndPromptUpdate(info, false)

openUpdateChannel('store')
openUpdateChannel('pgyer', 'https://www.pgyer.com/yourApp')
openUpdateChannel('url', 'https://example.com/download')
openUpdateChannel('apk', 'https://example.com/app.apk')

3. 后端字段建议（RemoteUpdateInfo）

hasUpdate / force / versionName / versionCode / title / content / channel / apkUrl / storeUrl / pgyerUrl / downloadPageUrl

对接真实接口：改 api/update.uts 中 fetchUpdateInfo() 为 fetchUpdateInfoRemote()。

上传 / 下载

import { uploadFile, downloadFile } from '@/utils/file-transfer.uts'

await uploadFile(localPath, '', 'file', true)
const file = await downloadFile('https://xxx/a.png', true, '')

上传地址默认 appConfig.uploadUrl（config/env.uts）。

头像裁剪上传

import { chooseAndUploadAvatar, pickUploadImageUrl } from '@/utils/avatar.uts'
// 或组件：
// <scaffold-avatar :src="avatar" @success="onOk" />

基于官方 uni.chooseImage 的 crop（方形头像默认 300×300）。不支持裁剪的端会降级为普通选图。

主题

内置明暗

import { toggleTheme, applyTheme, useThemeStore } from '@/store/theme.uts'
toggleTheme()
applyTheme('dark')

用户自定义

入口页：pages/theme/custom

import { applyCustomPrimary, applyCustomTheme, resetTheme } from '@/store/theme.uts'

applyCustomPrimary('#34c759') // 预设/自定义主色
applyCustomTheme({
  baseMode: 'light',
  primary: '#ff3b30',
  background: '',
  surface: '',
  text: ''
})
resetTheme()

• 模式：light / dark / custom
• 自定义会持久化到 THEME_CUSTOM
• 页面用 :style="{ backgroundColor: theme.tokens.xxx }" 绑定；导航栏由 applyNavigationBarTheme 同步
• 自定义页通过 scaffold-color-picker 支持 HEX 输入、色相条、SV 色格与常用色（非仅色卡点选）

演示路径

1. 首页：看环境 / 版本 / 主题，可切换 light/dark
2. 「脚手架能力演示」：请求、存储、检查更新、商店/蒲公英/第三方、下载、头像、拦截
3. 登录后进个人中心：头像裁剪上传并写回用户信息

编码规范

1. 页面唯一 <script setup lang="uts">
2. UTS 强类型，不用 undefined（用 null）
3. 禁止把函数引用当参数传递（如 fn 应先 await fn() 再传结果）
4. 禁止 return Promise.reject(...)（在 new Promise 内 reject）
5. 不要给官方 API 传 null 可选字段；setStorageSync 的 data 必须非 null
6. 不要把 NavigateToOptions 当成 UTSJSONObject（会 ClassCastException，跳转全挂）
7. 登录拦截依赖 utils/router 封装，勿对 navigateTo 挂错误类型的全局拦截器
8. 端差异收敛到 utils/platform / open-link / update
9. @/ + .uts 后缀引用模块

对接真实后端时

1. 改 config/env.uts、config/update.uts
2. fetchUpdateInfo 切远程；登录 Mock 换真实接口
3. 上传域名、小程序 download/upload 合法域名、Android 安装未知来源权限按各端要求配置

说明

脚手架保持零三方依赖。若需更强 Schema（地图/多商店），可自行接入插件市场 uts-openSchema，替换 utils/open-link.uts 内部实现即可。