uniappX前端开发模版框架

0 阅读41分钟

近期为了高效完成公司项目 KPI、减少团队重复造轮子成本,参考成熟开源项目 unibest 架构思想,基于最新 UniApp X 框架重构适配,打造了一套开箱即用的unibestX项目模板。 新项目不用从零配置路由、请求、全局拦截、UI 基础配置,拉取项目即可直接开发业务,极大缩短项目初始化周期。

unibestX - 最好的 uni-app X 开发框架

unibestX 由 uni-app X + Vue3 + UTS + Vite5 + Tailwind CSS + z-paging-x 构成,采用下一代 uni-app 原生开发技术栈,通过 HBuilderX 一键运行到 Android / iOS / 鸿蒙 / H5 / 微信小程序 五大平台。

内置 自定义 TabBar、Layout 布局、请求封装、登录拦截、路由守卫、Tailwind CSS、i18n 多语言、主题切换、沙盒极速调试 等基础能力,并提供 代码提示、自动格式化、统一配置 等辅助功能,让你编写 uni-app X 拥有 best 体验。

🤖 同时它也是一套「AI 原生」开发模板:项目自带 unibestX-skill(「1 个入口 + 8 个分册」的 uni-app X / UTS 规范知识库),Claude Code、Codex 等 AI Agent 克隆即可直接按项目规范写代码、生成页面骨架、自动排查跨端编译报错;运行时亦内置 AI 对话页与 SSE / Chunk 跨端流式传输能力。详见 🤖 AI 与 Skill 体系。

👉 在线 H5 演示📖 官方文档🐙 GitHub🍊 Gitee 镜像
aimageheir.github.io/uniBestXaimageheir.github.io/uniBestX/do…aimageheir/uniBestXhtwoO-cq/uni-best-x

🤖 Android 安装包真机体验(蓝奏云):

如果项目对您有帮助,请帮忙点个 Star ⭐ 支持一下!您的鼓励是作者持续维护的动力!


📖 目录

🚀 快速开始

1. 创建 / 克隆项目

  • 方式一:使用官方脚手架 create-unibestx(推荐):

    脚手架基于本仓库的分支生成项目,可交互式引导或一行命令完成创建:

    # 交互式创建(推荐),逐步选择 UI 库、功能特性与演示分包
    pnpm create unibestx my-app
    
    # 免安装直接运行
    npx create-unibestx my-app
    
    # 全局安装(提供 bestx / unibestx / create-unibestx 三个等价命令)
    npm i -g create-unibestx
    bestx my-app
    

    完整参数(--ui / --features / --subs / --package-manager / --keep-unused-modules 等)见 create-unibestx 文档。

  • 方式二:通过 degit 快速创建(不含历史提交记录):

    # 主分支(main,默认 Vapor 蒸汽模式,全面兼通 VDOM & Vapor)
    npx degit cq112233/unibestX my-project
    
    # Rice UI 官方支持分支(强烈推荐,团队持续维护)
    npx degit cq112233/unibestX#uniX-rice-ui my-project
    
  • 方式三:通过 git clone 克隆:

    # GitHub
    git clone https://github.com/cq112233/unibestX.git
    cd unibestX
    
    # Gitee(国内加速推荐)
    git clone https://gitee.com/htwoO-cq/uni-best-x.git
    cd uni-best-x
    
    # 或克隆 Rice UI 官方支持分支(推荐)
    git clone -b uniX-rice-ui https://github.com/cq112233/unibestX.git
    

2. 填写 AppID(请自行申请)

[!IMPORTANT] 项目内自带的 AppID 仅用于演示,请自行申请并替换为你自己的,否则无法真机运行、云打包与上传小程序。

平台申请入口填写位置
App(Android / iOS / 鸿蒙)DCloud 开发者中心 → 创建应用,获取 __UNI__ 开头的 AppIDmanifest.json 的顶层 appid
微信小程序微信公众平台 → 注册小程序,获取 wx 开头的 AppIDmanifest.json 的 mp-weixin.appid
  • 用 HBuilderX 打开项目后,双击 manifest.json 可视化界面也可直接填写,App 端点击「重新获取」可自动申请一个新的 DCloud AppID。
  • 微信小程序还需在微信公众平台后台配置 request 合法域名(对应 .env 的 VITE_SERVER_BASEURL)后才能正常请求接口。

3. 安装依赖

pnpm install

方式一的脚手架在生成时会询问「是否立即安装依赖」,已选择安装的项目可跳过本步。

4. 运行项目(支持热更新)

支持 命令行 CLI 与 HBuilderX 图形界面 两种开发方式。

[!WARNING] 使用 CLI 命令前,必须先启动 HBuilderX(需 5.24 及以上)。CLI 命令本质是通过正在运行的 HBuilderX 来编译运行项目,未打开时会报「未找到 HBuilderX」。App 端(Android / iOS / 鸿蒙)编译只能由 HBuilderX 完成。

🖥️ 方式一:命令行 CLI
pnpm dev:web            # 运行到 H5 / Web 端
pnpm dev:app-android    # 运行到 Android 原生端
pnpm dev:app-ios        # 运行到 iOS 模拟器(需 macOS + Xcode)
pnpm dev:app-ios:device # 运行到 iOS 真机(需连接 iPhone 并信任此电脑)
pnpm dev:app-harmony    # 运行到鸿蒙原生端(需 DevEco Studio)
pnpm dev:mp-weixin      # 运行到微信小程序
🛠️ 方式二:HBuilderX 图形化

用 HBuilderX 打开项目根目录,在顶部菜单选择:

平台操作路径
Android / iOS / 鸿蒙运行 → 运行到手机或模拟器,选择已连接的设备
H5运行 → 运行到浏览器
微信小程序运行 → 运行到小程序模拟器 → 微信开发者工具

5. 打包与发布

🖥️ H5:在自己服务器 / CI 上打包(推荐)

H5 支持在自己的服务器 / CI 上打包,脚本调用 HBuilderX 官方 CLI(cli publish)完成构建,产物完整(包含 src/sub 分包页面)。 ⚠️ 纯 CLI 的 uni build 产物不完整(分包页面不会编译进去),请勿使用。

# 1. 切换打包环境(默认生产环境,打测试包才需要切换)
pnpm env:test    # 打测试包:生成 .env.production.local(不影响 git)
pnpm env:prod    # 恢复生产环境:删除 .env.production.local

# 2. 打包 H5,产物输出到 unpackage/dist/build/web
pnpm build:h5

# 或一步到位
pnpm build:test  # = env:test + build:h5
pnpm build:prod  # = env:prod + build:h5

环境文件(四件套):

文件用途
.env公用变量,所有环境都会加载
.env.development开发环境,HBuilderX 运行 / pnpm dev:* 自动加载
.env.test测试环境,pnpm env:test 后打测试包
.env.production生产环境,默认即此环境,打正式包无需切换

💡 pnpm env:test 会把「公用 + 测试」合并写入 .env.production.local(Vite 生产模式优先加载它),pnpm env:prod 删除它即恢复生产。四个 env 文件本身不会被动修改。

接口地址(VITE_SERVER_BASEURL)各端规则:

  • H5:通过 .env 的 VITE_H5_USE_PROXY 切换——true 走反向代理(请求 /api,开发配 vite.config.ts 的 server.proxy,生产配 deploy/nginx.conf);false 直连 VITE_SERVER_BASEURL 完整域名(默认)。切换只改配置,不用动代码。
  • 微信小程序 / App(蒸汽与 VDOM 模式):统一读取 VITE_SERVER_BASEURL,固定直连完整域名;若误配 /api 相对路径会自动回退为默认完整域名。
  • 微信小程序:需在微信公众平台后台配置 request 合法域名。

服务器要求:

  • 安装 HBuilderX 官方 Linux 版(常见安装目录 /opt/hbuilderx/HBuilderX,命令行工具为 cli),或设置环境变量指定路径:export HBUILDERX_CLI_PATH=/opt/hbuilderx/HBuilderX/cli。
  • macOS / Windows 本机打包同样支持,脚本会自动查找常见安装路径(macOS 为 /Applications/HBuilderX.app/Contents/MacOS/cli)。
  • 脚本在构建前后会自动备份并还原 pages.json,不会污染工作区。

[!WARNING] App 端(Android / iOS / 鸿蒙)与小程序发布仍需使用 HBuilderX:原生 App 云打包 / 小程序上传依赖 HBuilderX 发行能力,命令行仅支持 H5。

🐳 H5:Docker 容器化部署(轻量交付,秒级打包)

项目提供业界标准的 「宿主机构建 + Nginx:alpine 极简容器」 部署方案(镜像仅约 25MB,打包仅需 1~2 秒,原生支持 amd64 与 arm64):

# 1. 测试环境:一键切换环境 -> H5 编译 -> 构建 Docker 镜像 -> 启动容器(访问 http://localhost:8081)
pnpm docker:build:test
pnpm docker:up:test

# 2. 生产环境:一键切换环境 -> H5 编译 -> 构建 Docker 镜像 -> 启动容器(访问 http://localhost:8080)
pnpm docker:build:prod
pnpm docker:up:prod

# 3. 停止容器
pnpm docker:down
  • 动态反代与环境变量:在 deploy/.env.test 与 deploy/.env.prod 中可直接配置映射端口与 API_UPSTREAM 动态代理后端地址,修改后执行 pnpm docker:up:* 即刻生效,无需重新构建镜像。
  • 详尽操作手册:详见 docs/guide/docker-deploy.md。
🛠️ HBuilderX 发行打包
平台操作路径
Android发行 → 原生App-云打包 或 原生App-本地打包
iOS发行 → 原生App-云打包(需 Apple 开发者证书)
鸿蒙发行 → 原生App-鸿蒙
H5发行 → 网站-H5手机版,产物在 unpackage/dist/build/web
微信小程序发行 → 小程序-微信,再通过微信开发者工具上传
其他常用脚本
pnpm lint           # ESLint 检查(含 UTS 强类型与 UVUE 模板规则)
pnpm lint:fix       # ESLint 自动修复
pnpm lint:style     # Stylelint 样式检查(支持 SCSS / CSS / UVUE <style>)
pnpm lint:style:fix # Stylelint 样式自动修复
pnpm lint:all       # 全量代码与样式校验(ESLint + Stylelint)
pnpm docs:dev       # 本地启动 VitePress 文档站
pnpm gen:uts-dts    # 生成 UTS 类型声明(.d.uts.ts)
pnpm check:uts-dts  # 校验 UTS 类型声明是否为最新(CI 用)

⚙️ 环境要求

依赖版本要求
Node>= 22
pnpm>= 7.30
HBuilderX5.24 及以上(App 端蒸汽模式必需;旧版本可切 VDOM 模式运行)
Vue Official>= 2.1.10
TypeScript>= 5.0
JDK>= 17(Android 平台)
Android SDKAndroid 平台
XcodeiOS 平台,仅 macOS
DevEco Studio鸿蒙平台

✨ 特性

  • 🚀 uni-app X(Vapor 默认 + VDOM 兼容) — 默认启用 Vapor 蒸汽模式(无虚拟 DOM 高性能原生渲染),同时全面兼容传统 VDOM 模式,可在 manifest.json 自由切换
  • 💪 Vue3 + Vite5 — 最新前端技术栈,极速开发体验
  • 🎨 Tailwind CSS — 原子化 CSS 引擎(v4 + weapp-tailwindcss),全端通用,方括号任意值语法
  • 📦 多分支 UI 选型 — main 分支为无 UI 库纯净基线(原生组件 + Tailwind CSS);另有 uniX-rice-ui(Rice UI,官方团队持续维护)与 uniX-uview-ultra(内置深度修复版)两个开箱即用分支
  • 📜 z-paging-x — 强大的分页列表组件(已针对 Android 嵌套手势协商、Flex 布局与 type="nested" 深度适配)
  • 🏝️ 多策略 TabBar 体系 — 5 种运行策略 + 2 种视觉形态,支持角标徽标与全端主题联动
  • ⚡ 沙盒独立调试模式 — 大型项目本地开发只编译当前页面,秒级热更新,启动直达目标页
  • 🔧 Pinia 持久化 — Vapor 走官方 Pinia,VDOM 走 x-pinia-s,按平台自动路由,开箱即用
  • 🌐 i18n 多语言 — 内置中英文切换,支持自动检测系统语言
  • 🛡️ 路由守卫 — 黑名单/白名单策略,灵活的登录拦截与登录后回跳
  • 🌈 动态主题 — theme.json 单源色板,CSS 变量驱动的明暗主题切换
  • 📊 ECharts — 图表组件支持
  • 🔌 请求封装 — 基于 lime-request,支持多域名、Token 自动续期、SSE 流式传输
  • 📤 文件上传 — 基于原生 uni.uploadFile 统一封装,支持 OSS 上传与进度回调
  • 🐳 H5 Docker 极速部署 — 宿主机构建 + Nginx:alpine 轻量容器运行(~25MB,秒级打包),内置动态环境变量反代与 Hash 路由兜底
  • 🤖 AI 原生开发模板 — 内置 unibestX-skill(1 入口 + 8 分册),AI Agent 克隆即可按项目规范写代码;运行时自带 AI 对话页与 SSE 流式传输
  • 🔍 工程化代码规范与 Git 提交拦截 — 深度整合 ESLint(内置针对 UTS 强类型与 UVUE 模板的自定义规则)、Stylelint(针对 SCSS、uni-app 特有单位与标签适配)、Husky、lint-staged 以及 Commitlint,提交时自动运行增量校验与友好中文规范提示,把跨端隐患拦截在提交前
  • 🧰 官方脚手架 — pnpm create unibestx 一键创建项目:UI 库三选一、功能与 12 个演示分包按需裁剪,生成后自动跑四查自检

📦 推荐的 UI 组件库

unibestX 提供多分支与多种 UI 组件库选择,可根据项目架构与需求灵活选用:

组件库简介推荐分支 / 官网维护状态
Rice UI(强烈推荐)专为 uni-app X 打造的现代 UI 组件库,完美支持 Vapor 与 VDOM 模式无缝切换,由 Rice UI 官方团队持续维护与技术支持。uniX-rice-ui 分支 / riceui.cn团队持续维护与迭代
uview-ultra专为 uni-app X 打造的 UI 库,uniX-uview-ultra 分支内置作者深度修复版,已兼容 Vapor/VDOM,基础功能基本够用。uniX-uview-ultra 分支 / uview-ultra.lingyun.net已停止后续维护与定制
TMUI功能丰富、高度可定制的企业级组件库,提供完善的业务组件和主题系统。tmui.design社区维护
Lime UI社区活跃的 uni-app X 组件库,组件风格清新,覆盖常用移动端场景。limex.qcoon.cn社区维护

💡 选型建议:新项目或需要长期维护支持,优先选 uniX-rice-ui 分支;只需基础组件可切 uniX-uview-ultra 分支(内置作者深度修复版);不想引入任何第三方 UI 组件库就直接用 main(默认分支) —— 它是无 UI 库的纯净基线,原生组件 + Tailwind CSS 起步。

🤖 AI 与 Skill 体系

unibestX 不只是一个运行时的跨端模板,也是一套为 AI Agent 准备充分的开发模板:项目内直接内置了 uni-app X 领域知识库(unibestX-skill)与会话级开发规约,让 Claude Code、Codex 等 AI 工具克隆后无需额外提示词,即可按项目既定规范产出代码。

1. unibestX-skill — 项目专属 uni-app X / UTS 规范库

这是与项目强绑定的核心技能,也是仓库中唯一保留的技能,采用 「1 个入口 + 8 个分册」 结构,把 UTS 强类型约束、跨端样式限制与本项目的生产级写法沉淀成可被 AI 直接检索的知识库。

分册内容
SKILL.md(入口,常驻)概述 + 分册导航 + A.1 快速对照表 + A.2 红线清单
1-uts-syntax.mdUTS 强类型系统与语法核心铁律(UTS110111163 等报错成因)
2-styling.mdCSS & Tailwind 样式引擎与原生渲染限制
3-runtime.md跨端运行时与 VDOM / Vapor 渲染模式约束
4-examples.md5 个项目内生产级标杆案例(页面骨架、TabBar、二级详情页、滚动与下拉刷新)
5-codegen.md代码生成流程与标准页面模板
6-page-component-spec.mdAI 页面层级与组件设计规范(页面高内聚、三级防过度拆分、容器与纯展示解耦、Mock 接口契约化)
7-api-spec.mdAPI 接口层规范(一页一目录、契约类型用 type、Mock 数据集与接口函数同层、后端就绪只换函数体)
8-utils-spec.md项目核心工具库使用规范(系统信息 src/utils/systemInfo、环境变量 src/utils/env、通用工具优先原则)

工作机制:入口文件只常驻导航与红线清单,AI 命中条目后必须继续读取对应分册核对完整正反例才允许改代码。

2. 任务复杂度分级与门槛控制

在开发过程中,根据 CLAUDE.md 与 AGENTS.md 严格匹配任务复杂度,避免过度设计与流程冗长,按层级匹配执行方案:

复杂度典型场景做法
第 1 级单行修改、CSS 样式、文案、简单配置主代理直接改 + 轻量验证,不派生代理、不建 worktree、不写单测
第 2 级单文件开发、独立 UI 页面、常规 Bug 修复主代理直做;Bug 成因不明时先定位根因再改
第 3 级跨多文件重构、核心业务系统升级先澄清需求 / 写计划文档,再分步实现

不因任务大小豁免的底线:声称完成 / 已修复 / 测试通过之前,必须实际运行验证命令并确认输出。

3. AI 开发规约文件

文件作用
CLAUDE.mdClaude Code 会话级规约(技能路由、内置工具优先复用、基础设施按既有配置走)
AGENTS.md通用 AI Agent 规约(Codex 等)
.agents/rules/uniappx.mduni-app X 开发规范,编写 .uvue / .uts / .ts / .scss 前必读

📌 技能目录有两份副本:.claude/skills/(Claude Code)与 .agents/skills/(其他 Agent),修改技能时需同步一致。

4. 运行时的 AI 能力

模板同时预置了 AI 应用所需的运行时能力,可直接作为 AI 类 App 的起点:

  • AI 对话页 — src/pages/ai/(含 TabBar 中间鼓包按钮入口 AiView)
  • 跨端流式传输 — src/http/stream.uts 提供 SSE / Chunk 流式请求;src/utils/rxjs-lite/ 提供轻量流式算子,配套 src/sub/rxjsDemo 流式演示页
  • Markdown 渲染 — 内置 mp-html 与 kux-marked,支持 Markdown 排版与代码块展示
  • 流式接口配置 — 通过 .env 的 VITE_STREAM_URL 指定(留空时演示页自动使用本地模拟流)

📱 各端首页截图

微信小程序   |   Android   |   H5   |   iOS   |   鸿蒙

平台兼容性

AndroidiOS鸿蒙H5微信小程序
√√√√√

注意:uni-app X 目前兼容以上 5 个端平台,其他小程序平台暂不支持。

📁 项目结构

unibestX/
├── plugins/                      # Vite 构建插件
│   ├── vite-plugin-uni-pages.ts  #   自动文件路由插件(生成 pages.json / definePage 支持)
│   ├── uni-layouts-plugin.ts     #   跨端 Layout 布局插件(default / empty / navbar)
│   ├── vite-plugin-tabbar-views.ts # 单页 TabBar 脚手架与视图自动生成插件
│   ├── vite-plugin-clean-logger.ts # 过滤编译期控制台噪音日志
│   ├── vite-plugin-tailwind-hmr.ts # Tailwind 入口 CSS 变更的热更新加速
│   └── root-plugin.ts            #   自动包裹 App.ku.uvue 全局根骨架组件
├── scripts/                      # 构建与环境切换脚本
│   ├── build-h5.mjs              #   H5 打包(调用 HBuilderX cli publish)
│   ├── switch-env.mjs            #   env:test / env:prod 环境切换
│   ├── gen-uts-dts.mjs           #   UTS 类型声明生成与校验
│   ├── check-tabbar-surface.mjs  #   TabBar 接口面校验
│   └── router-guard-test/        #   路由守卫决策矩阵测试(node 直跑,无需测试框架)
├── .husky/                       # Git 提交钩子(pre-commit / commit-msg)
├── .commitlintrc.cjs             # Commitlint 提交信息规范配置
├── stylelint.config.mjs          # Stylelint 样式规范配置(支持 SCSS / UVUE)
├── eslint.config.mjs             # ESLint 扁平化配置(含 UTS 专属规则插件)
├── Dockerfile                    # H5 生产部署轻量容器(nginx:alpine)
├── docker-compose.yml            # H5 容器编排服务(h5-test / h5-prod)
├── deploy/                       # 生产与测试部署配置
│   ├── nginx.conf                #   Nginx 动态反代与静态托管配置
│   ├── .env.test                 #   测试环境 Docker 变量配置
│   └── .env.prod                 #   生产环境 Docker 变量配置
├── docs/                         # VitePress 文档站源码(guide/ 下为各专题)
├── .claude/skills/               # AI 技能(Claude Code):仅 unibestX-skill(1 入口 + 8 分册)
├── .agents/                      # AI 技能与规约(其他 Agent)
│   ├── skills/                   #   与 .claude/skills 一一对应的技能副本(仅 unibestX-skill),需保持同步
│   └── rules/uniappx.md          #   uni-app X 开发规范(编写 .uvue/.uts 前必读)
├── CLAUDE.md / AGENTS.md         # AI Agent 会话级规约(技能路由、内置工具优先复用等)
├── src/
│   ├── api/                      # API 请求模块(foo.uts / user.uts / auth.uts 等)
│   ├── assets/                   # 静态资源(图标、图片等)
│   ├── components/               # 公共业务组件
│   │   ├── NavBar/               #   自定义通用导航栏组件
│   │   ├── NestedScroll/         #   自研嵌套滚动组件
│   │   └── TabbarMaskModal/      #   TabBar 遮罩弹层
│   ├── http/                     # HTTP 客户端封装(基于 lime-request)
│   │   ├── request.uts           #   HttpClient 核心类与拦截器
│   │   ├── stream.uts            #   SSE / Chunk 流式请求封装
│   │   ├── types.uts             #   HTTP 响应与请求类型定义
│   │   └── tools/enum.uts        #   HTTP 状态码与业务枚举
│   ├── i18n/                     # 国际化多语言
│   │   ├── index.uts             #   i18n 实例与响应式切换
│   │   └── locales/              #   中英文语言包(zh-Hans / en)
│   ├── layouts/                  # 页面布局模板
│   │   ├── default.uvue          #   默认页面布局
│   │   ├── empty.uvue            #   空白全屏布局
│   │   └── navbar.uvue           #   自定义导航栏布局(需配 navigationStyle: 'custom')
│   ├── pages/                    # 主包页面(TabBar 页面)
│   │   ├── index/                #   首页(概览、常用入口)
│   │   ├── basic/                #   基础组件与工具演示
│   │   ├── function/             #   原生能力展示(设备、系统信息、扫码等)
│   │   ├── ai/                   #   AI 助手对话演示
│   │   └── me/                   #   个人中心与系统设置
│   ├── router/                   # 路由守卫与导航控制
│   │   ├── index.uts             #   路由模块统一出口
│   │   ├── config.uts            #   页面登录白名单 / 黑名单策略
│   │   ├── interceptor.uts       #   全局路由跳转拦截器
│   │   └── toLoginPage.uts       #   跳转登录页逻辑封装
│   ├── store/                    # 状态管理(双模式自适应)
│   │   ├── index.uts             #   门面:按平台条件编译路由到 vapor / vdom
│   │   ├── types.uts             #   共享类型(与平台无关,恒定向外转发)
│   │   ├── types.d.uts.ts        #   类型声明
│   │   ├── vapor/                #   官方 Pinia 实现(App Vapor / H5 / Web / 小程序)
│   │   │   ├── index.ts          #     Pinia 实例 + pinia-plugin-persistedstate
│   │   │   ├── app.ts            #     应用全局状态(主题、语言等)
│   │   │   ├── token.ts          #     Token 鉴权状态(单 / 双 Token 自动续期)
│   │   │   └── user.ts           #     当前登录用户信息
│   │   └── vdom/                 #   x-pinia-s 实现(App VDOM 原生端)
│   │       ├── index.uts         #     Pinia 实例(UTS 强类型版)
│   │       ├── app.uts / token.uts / user.uts
│   ├── style/                    # 全局样式(Tailwind、变量等)
│   ├── sub/                      # 应用分包页面(按需加载,13 个演示模块)
│   │   ├── auth/                 #   登录、注册、找回密码
│   │   ├── crypto/               #   加密解密演示
│   │   ├── device/               #   原生设备能力
│   │   ├── httpDemo/             #   HTTP 请求演示
│   │   ├── layoutDemo/           #   Layout 布局示例
│   │   ├── lodash/               #   UTS 版 Lodash
│   │   ├── nested-scroll/        #   自研嵌套滚动
│   │   ├── rxjsDemo/             #   rxjs 流式演示
│   │   ├── tailwindcss/          #   weapp-tailwindcss 示例
│   │   ├── test/                 #   页面间 URL 参数传递测试
│   │   ├── time/                 #   时间日期操作
│   │   ├── uiTest/               #   UI 测试与排版
│   │   └── zpaging/              #   z-paging-x 分页列表各种场景
│   ├── tabbar/                   # 底部 TabBar 体系
│   │   ├── internal/             #   模块内部实现(不对消费者暴露,请走 index.uts 门面)
│   │   │   ├── strategy.uts      #     策略枚举与模式判定
│   │   │   ├── metrics.uts       #     尺寸常量与视口 / 主题计算
│   │   │   ├── state.uts         #     列表与激活状态、路径匹配、激活订阅
│   │   │   ├── navigate.uts      #     跳转行为与原生中间按钮监听
│   │   │   └── native.uts        #     平台桥接(隐藏原生 tabbar)
│   │   ├── ui/                   #   TabBar 视图层
│   │   │   ├── capsule/          #     悬浮胶囊风格
│   │   │   ├── default/          #     标准贴底风格(含 midButton 鼓包)
│   │   │   └── template.uvue     #     TabBar 视图模板
│   │   ├── components/           #   容器与调度组件(TabViews、TabContent)
│   │   ├── tabbar.uvue           #   TabBar 入口组件
│   │   ├── index.uts             #   模块唯一门面(单层 export *)
│   │   ├── config.uts            #   TabBar 统一配置(支持 type 风格切换与 midButton)
│   │   └── types.uts             #   TabBar 强类型定义
│   ├── types/                    # 全局 TypeScript / UTS 类型定义
│   │   └── uni.d.ts              #   definePage 宏、Vue 宏与全局 API 类型补全
│   └── utils/                    # 全局工具函数(10 个模块,统一走 index.uts 导出的对象)
│       ├── env/                  #   环境变量读取(getApiBaseUrl / getTabBarMode 等)
│       ├── route/                #   取路由与路径工具
│       ├── theme/                #   主题色与明暗模式工具
│       ├── i18n/                 #   多语言辅助工具(t / $t)
│       ├── toast/                #   全局 Toast 轻提示
│       ├── systemInfo/           #   屏幕、安全区与系统信息
│       ├── upload/               #   文件上传封装(OSS 上传、进度回调)
│       ├── backPress/            #   Android 物理返回键双击退出
│       ├── refresh/              #   下拉刷新与滚动事件联动
│       └── rxjs-lite/            #   轻量流式处理工具
├── uni_modules/                  # uni-app 扩展插件模块(39 个)
│   ├── z-paging-x/               #   深度优化适配的分页组件
│   ├── unix-crypto/              #   跨端加密解密库(AES/DES/RSA/MD5/SHA/HMAC/Base64/UUID)
│   ├── unix-router-guard/        #   路由守卫底层插件
│   ├── x-pinia-s/                #   UTS 版 Pinia(VDOM 模式使用)
│   ├── iRainna-lodash/           #   UTS 版 Lodash 工具库
│   ├── lime-request/             #   HTTP 请求核心库
│   ├── lime-i18n/                #   国际化核心库
│   ├── lime-signature/           #   手写签名板组件
│   ├── e-chart/                  #   ECharts 图表适配组件
│   └── ...                       #   其他官方 / 三方 uni_modules(UI 组件库请按分支选型:Rice UI / uview-ultra)
├── js_sdk/                       # JS / UTS SDK 资源
├── App.ku.uvue                   # 全局根包裹组件(动态主题注入、全局 Toast 容器)
├── main.uts                      # 应用主入口文件
├── main.css                      # Tailwind 入口样式(含 iconify)
├── theme.json                    # ⭐ 明暗主题色板唯一真源(light / dark)
├── pages.config.json             # ⭐ 页面路由与全局配置(路由与页面配置请改这里)
├── pages.json                    # ⚠️ 自动生成的页面路由表(编译产物,请勿手动编辑)
├── manifest.json                 # 应用配置清单(多端 AppID、权限、vapor 开关等)
├── vite.config.ts                # Vite 构建配置(Tailwind 与 5 个自定义插件)
├── uni.scss                      # 全局 SCSS 变量与主题注入
└── tsconfig.json                 # TypeScript / UTS 编译配置

[!WARNING] 请勿覆盖内置的定制组件。uni_modules/ 下的 z-paging-x.uvue 等组件都已由作者做了深度定制修改与修复(针对 Android 原生嵌套手势协商、type="nested" 架构支持、Flex 布局及各端 CSS 解析限制等)。请勿直接从官方插件市场重新下载覆盖,否则多端兼容性与手势机制可能失效。


🧩 核心功能说明

内置工具库(src/utils)

[!IMPORTANT] 动手实现任何通用能力之前,先查这里。 src/utils/ 下已有 10 个开箱即用的模块,覆盖取路由与路径、取主题色、读环境变量、多语言文案、提示弹窗、返回键接管、下拉刷新与导航栏控制、文件上传、系统与安全区尺寸、流式处理。 严禁重复造轮子 —— 例如自己写 uni.getSystemInfoSync()、裸写 setInterval 做防抖、直接读 import.meta.env.VITE_XXX。

导入约定(@ 指向项目根,且 .uts 后缀必须保留,否则会丢类型补全并报 TS2307):

import { toast, toastSuccess } from '@/src/utils/toast/index.uts';
import { getApiBaseUrl, isVaporMode } from '@/src/utils/env/index.uts';
import { sys } from '@/src/utils/systemInfo/index.uts';
模块用途主要 API
env/环境变量统一读取(禁止裸读 import.meta.env)getApiBaseUrl() getApiSecondaryUrl() getAppTitle() getAppVersion() getTabBarMode() getCurrentEnv() getCurrentEnvName() isDev() isTest() isProd() isVaporMode() getStreamUrl() getOssUploadUrl();实例 env
route/取当前路由 / 路径 / 参数、页面栈深度、路径规范化getCurrentPath() getCurrentRoute() getQueryString(url) getPageStackLength() cleanPath(path) isSamePath(a, b) ensureLeadingSlash() removeLeadingSlash();实例 route
systemInfo/屏幕尺寸、安全区、导航栏 / TabBar 高度(响应式 computed)windowWidth windowHeight screenWidth screenHeight statusBarHeight navBarHeight tabBarHeight safeAreaBottom availableHeight menuRect updateSystemInfo() getScrollHeight();实例 sys
theme/主题色与明暗模式:读取、应用、监听themeColor isDarkMode(mode) getThemeTokens(isDark) getRootThemeStyle() applyThemeColor(color) applyThemeMode(mode, isDark) applyNavbarTheme(isDark) watchThemeChange(cb);实例 theme
toast/全局轻提示(统一风格,替代裸 uni.showToast)toast(msg) toastSuccess(msg) toastError(msg) toastWarning(msg) toastPrimary(msg) showToast(options);实例 toastUtils
i18n/非 Vue 环境下的多语言文案与导航栏 / TabBar 文案设置t(key, named) $t(key, named) getI18nText(key) setTabbarItem() setNavigationBarTitle(key);实例 i18nUtils
refresh/下拉刷新、滚动到底、导航栏标题与可见性、状态栏可见性的跨端联动onNavbarPageScroll(cb) onNavbarReachBottom(cb) onNavbarPullDownRefresh(cb) stopNavbarPullDownRefresh() setNavbarTitle(t) setNavbarVisible(v) setHideNavbar(h) setHideStatusBar(h) isPageScrollDisabled isPageRefresherDisabled;实例 refresh
backPress/Android 物理返回键双击退出handleBackPressExit(): boolean
upload/文件上传(OSS 上传、进度回调、多后端返回格式兼容)uploadFile(options) uploadOssFile(filePath) 类型 UploadFileOptions;实例 upload
rxjs-lite/轻量流式处理(不依赖 RxJS 全量包)Observable Subject Subscription;创建 fromArray interval timer throwError;算子 map scan filter toArray distinctUntilChanged debounceTime throttleTime take takeUntil tap startWith catchError finalize unsubscribeAll

💡 每个模块同时提供扁平函数导出与类实例导出(如 toast() 与 toastUtils.toast()),按项目风格任选其一即可。 每个模块都配有 index.d.uts.ts 类型声明文件,供编辑器补全;修改模块后可用 pnpm gen:uts-dts 重新生成、pnpm check:uts-dts 校验。

环境变量配置(.env)

项目的环境配置采用 「公用 + 按环境拆分」 的四文件结构,改配置只改 .env,不要改代码。

1. 公用变量(.env,所有环境都加载)
变量默认值说明
VITE_APP_TITLEunibestX应用名称(H5 标题等)
VITE_APP_VERSION1.0.0应用版本号。⚠️ 构建时会被 vite.config.ts 从 package.json 的 version 覆盖
VITE_TABBAR_MODE4TabBar 运行策略,0~4,详见底部 TabBar 体系
VITE_DEFAULT_THEME#37c2bc默认主题主色调(十六进制色值)
VITE_DEFAULT_LOCALEzh-CN默认语言(zh-CN / en-US)
VITE_H5_USE_PROXYfalseH5 是否走反向代理,仅 H5 生效;true 请求 /api,false 直连完整域名
VITE_STREAM_URL/stream/chat流式演示接口,须支持 chunked / SSE;留空时演示页自动使用本地模拟流
VITE_DEV_SANDBOXfalse沙盒独立调试开关,详见沙盒独立调试模式
VITE_DEV_SANDBOX_PAGES—沙盒目标页面,支持单个 / 逗号分隔多个 / 目录/* 通配
2. 按环境拆分的变量(.env.development / .env.test / .env.production)
变量说明
VITE_ENV_TYPE环境标识:development / test / production
VITE_ENV_NAME环境中文名(EnvCard 等界面组件展示用)
VITE_SERVER_BASEURL接口主域名(完整域名)。H5 直连、App、小程序均读取此值
VITE_SERVER_BASEURL_SECONDARY备用 / 第二接口域名,配合多域名请求使用
VITE_UPLOAD_BASEURL上传接口基础域名,详见文件上传
VITE_UPLOAD_PATH上传接口路由路径
3. 使用方式与注意事项
pnpm env:test    # 合并「公用 + 测试」→ 生成 .env.production.local(不影响 git)
pnpm env:prod    # 删除 .env.production.local → 恢复生产环境
  • 四个 env 文件本身不会被脚本改写,env:test 通过生成 .env.production.local(Vite 生产模式优先加载)覆盖生效。
  • 取值一律走 src/utils/env/index.uts(如 getApiBaseUrl()),不要直接读 import.meta.env.VITE_XXX —— 模块内含兜底默认值与类型转换。
  • App / 小程序固定直连完整域名,不受 VITE_H5_USE_PROXY 影响。该平台分支下若 VITE_SERVER_BASEURL 误配成 /api 这类相对路径,src/http/request.uts 会在编译期自动回退为默认完整域名(回退逻辑在请求层,不在 env/index.uts)。
  • 新增环境变量时,同步在 src/utils/env/index.uts 中补一个带兜底值的 getter。

页面路由与配置 (uni-pages)

本项目内置自动文件路由插件 vite-plugin-uni-pages,递归扫描 src/pages 主包与 src/sub 分包目录,实时维护生成 pages.json 并同步 pages.config.json。

[!WARNING] 请勿直接手动修改 pages.json! pages.json 是 Vite 插件的自动构建产物。每次在 HBuilderX 中运行、保存代码或打包时,插件都会根据源配置重新生成并完全覆盖它。

路由与页面配置使用说明(双向自动同步):

  1. 方式一:在页面代码中通过 definePage 或 <route> 配置(推荐) 直接在页面 .uvue 中内联声明。当页面写有 definePage 或 <route> 时,插件会自动双向同步 pages.config.json 和 pages.json:

    <script setup lang="uts">
    definePage({
      layout: 'navbar',
      style: {
        navigationBarTitleText: '基础',
        navigationStyle: 'custom'
      }
    })
    </script>
    
  2. 方式二:在根目录 pages.config.json 中配置 当页面中没有写 definePage 时,直接在 pages.config.json 中定义全局 globalStyle、tabBar 以及各页面的 style,保存后插件也会实时自动同步到 pages.json:

    {
      "path": "src/pages/basic/basic",
      "layout": "navbar",
      "style": {
        "navigationBarTitleText": "基础",
        "navigationStyle": "custom"
      }
    }
    

[!IMPORTANT] 任何 layout: 'navbar' 的页面,style.navigationStyle 必须显式写 'custom',漏写会让导航栏、返回箭头、状态栏占位静默消失且不报错。

沙盒独立调试模式 (Page Sandbox)

在大型多页面或复杂分包项目中,每次热更新或多端(尤其是 App 原生端)编译如果都全量编译所有页面,不仅构建耗时,还容易受到其他页面临时编译报错的干扰。

为此,unibestX 原创打造了 沙盒独立调试模式:本地开发阶段可将编译范围精准锁定为当前正在编写的单个页面或特定模块,极速秒级编译,且应用启动直达目标调试页面!

               沙盒独立调试模式 (Page Sandbox) 运行流程
 ┌─────────────────────────────────────────────────────────────────┐
 │ 开启方式 A: 代码级 definePage({ debug: true, debugHome: true })   │
 │ 开启方式 B: 环境级 .env (VITE_DEV_SANDBOX=true,优先级更高)       │
 └───────────────────────────────┬─────────────────────────────────┘
                                 ▼
           ⚡ 触发 vite-plugin-uni-pages 智能裁剪过滤
 ┌─────────────────────────────────────────────────────────────────┐
 │ 1. 动态生成 pages.json: 仅包含选中的沙盒页面,目标页置顶 pages[0] │
 │ 2. 严密保护 pages.config.json: 沙盒期间绝不回写,全量配置 100% 完整 │
 │ 3. TabBar 智能协同: 单页调试保持底部 UI 占位并优雅拦截未编译页面 │
 │ 4. 生产构建强制熔断: 打包 (build:h5 等) 自动恢复全量,严防调试泄露│
 └─────────────────────────────────────────────────────────────────┘
1. 两种开启方式

方式一:代码内 definePage 声明(极简轻便,推荐单页秒开)

直接在目标页面(主包或 src/sub 分包均可)的顶部脚本中配置 debug: true:

<script setup lang="uts">
definePage({
  debug: true,       // 开启当前页面独立沙盒调试(仅编译包含此标记的页面)
  debugHome: true,   // 强制置顶为应用冷启动首页(排在 pages[0];全局仅允许 1 个)
  layout: 'navbar',
  style: {
    navigationBarTitleText: '登录页调试',
    navigationStyle: 'custom'
  }
});
</script>

💡 调试完毕:只需将 debug: true 改回 false(或直接删除),保存代码后无需重启,自动秒级恢复全量页面编译。

方式二:.env 环境变量配置(最高优先级,支持批量 / 通配符)

在根目录 .env(或 .env.development)中开启沙盒模式并指定目标页面:

# 开启本地开发沙盒模式
VITE_DEV_SANDBOX=true

# 指定需要独立调试的页面列表(支持单个、逗号分隔多页)
VITE_DEV_SANDBOX_PAGES=src/sub/auth/login,src/pages/me/me

# 也支持目录通配符批量调试(例如调试 auth 模块下全部页面):
# VITE_DEV_SANDBOX_PAGES=src/sub/auth/*
2. 优先级与安全保护机制 🛡️
  1. 环境级最高优先级(.env > 代码标记)
    • 只要 .env 中 VITE_DEV_SANDBOX=true,完全以 .env 指定的页面列表为主,自动覆盖代码中分散的 debug 标记;
    • 当 .env 中 VITE_DEV_SANDBOX=false 时,自动平滑回退使用代码中的 definePage({ debug: true }) 标记。
  2. debug: false 一票否决权
    • 页面显式配置了 debug: false 时,无论是否配置了 debugHome,一律彻底排除出沙盒列表,严防误引入。
  3. 全量配置文件严格保护
    • 沙盒调试期间,插件绝对不会回写 pages.config.json,全量项目路由永远安全完整。
  4. TabBar 智能协同与 UI 还原
    • 多 Tab 页面调试(命中 >= 2 个 Tab):自动保留合法的 tabBar 供原生切换;
    • 单 Tab 页面调试(仅命中 1 个 Tab):系统级 tabBar 节点自动剔除(防止 uni-app 报路由缺失错误),但界面底部自定义 TabBar 依然 100% 保持渲染(保证 UI 视觉和底部安全区一致);点击未编译 Tab 时自动弹出轻提示 💡 沙盒调试中:目标页面未编译,不白屏、不报错。
  5. 生产发版打包安全熔断
    • 执行 pnpm build:h5 或正式打包发版时,插件会自动判定生产模式并强制熔断沙盒模式,100% 输出完整项目全量页面,绝无将调试配置带入线上的风险!

VDOM 模式与 Vapor 蒸汽模式切换

什么是 Vapor 蒸汽模式?

uni-app X 推出了新一代的 蒸汽模式(Vapor)。新版渲染引擎性能远超原生,考虑到 AI 友好度、动态性 以及老 uni-app 用户的升级,蒸汽模式下改用普通的 TS / JS 编写:

  • 蒸汽模式下不再依赖 UTS 的原生编译能力:拥有 JS 的动态性、非常强的 AI 友好度,渲染性能又超过原生;
  • 如果写成 UTS,Android 和 iOS 也会通过 uts2js 运行在 JS 引擎上;
  • 鸿蒙(HarmonyOS) 目前运行在 ArkTS 引擎上,未来为了热更新,也会提供运行在 JS 引擎上的选项;
  • 蒸汽模式之后,UTS 语言的主要作用是开发 UTS 原生插件:仅 UTS 插件(utssdk 目录)继续保留 UTS 向 Kotlin / Swift / ets 的编译能力。

🚀 从 2026 年起,新的蒸汽模式将逐渐替代老的 VDOM 模式。

本项目 main 分支全面兼通两种模式,默认采用 Vapor 蒸汽模式。当前生效值来自根目录 manifest.json:

{
  "uni-app-x": {
    "styleIsolationVersion": "2",
    "vapor": true,                    // true = Vapor 蒸汽模式(本项目默认);false = 传统 VDOM 模式
    "vapor-render-target": "bytecode"
  }
}

💡 作者建议优先使用 Vapor 模式:

  • 开发更省心:Vapor 模式下 Android 端语法要求不那么严格,许多 UTS 强类型检查会更宽松;
  • 注意切换风险:一旦在 Vapor 模式下开发过,之后若再切换回 VDOM 模式,之前可正常编译的代码可能会报类型或语法错误(VDOM 模式编译检查更严格);
  • 最终看个人选择:追求开发体验、少踩编译报错建议选 Vapor;追求最大兼容性与传统写法生态可保持 VDOM。

⚠️ 注意:manifest.json 的 vapor 开关仅对 App 端(Android / iOS / 鸿蒙) 生效。框架在 uni-cli-shared 中对 Web(H5)与全部小程序平台强制清除蒸汽标记(这两类平台本就是 JS 运行时),因此它们的 VUE3-VAPOR 恒为 false。项目已在 src/store/index.uts 中按平台名显式放行,让 Web / 小程序也走官方 Pinia。

📲 真机双模式 APK 对比体验:见文首「Android 安装包真机体验」小节。

底部 TabBar 体系

项目内置成熟健壮、全端兼容的 多策略 + 多形态 TabBar 体系,彻底解决了传统 uni-app 项目在多端(尤其是 App-Android/iOS、鸿蒙、微信小程序)下原生 TabBar 白屏闪烁、状态丢失、鼓包兼容差等痛点。

1. 运行策略模式(.env 中的 VITE_TABBAR_MODE)

可在根目录 .env 中通过 VITE_TABBAR_MODE 自由切换 5 种底层运行策略(当前默认 4):

模式值策略名称页面缓存底层路由实现适用场景与特性说明
4SINGLE_PAGE_TABBAR
【当前默认・首推】单页面容器保活模式
天然终极保活单页面视图显隐(免路由跳转)【强烈推荐・体验最佳】 全部 Tab 页面作为子视图挂载于 TabViews.uvue 容器中,0ms 秒级平滑切换、零白屏、零闪烁,输入框内容、长列表滚动位置天然保活不丢失。
2CUSTOM_TABBAR_WITH_NATIVE
带缓存多页面自定义模式
支持缓存uni.switchTabpages.json 生成原生底座并安全隐藏,保留各 Tab 独立页面组件状态与滚动位置缓存,通过原生 switchTab 驱动。
3CUSTOM_TABBAR_WITHOUT_NATIVE
纯多页面自定义模式
不缓存uni.redirectTopages.json 中无 tabBar 节点,每次切换重新触发页面生命周期与重新请求接口。
1NATIVE_TABBAR
纯原生 TabBar
支持缓存uni.switchTab纯原生 pages.json TabBar 渲染(⚠️ 原生 midButton 在微信小程序 / 鸿蒙 / iOS(Vapor) 端官方不支持)。
0NO_TABBAR
无 TabBar
无无纯单页、登录页或不需要 TabBar 的应用场景。
2. 视觉呈现形态(src/tabbar/config.uts)

在自定义模式(模式 2 / 3 / 4)下,可通过 src/tabbar/config.uts 的 type 字段一键切换 UI 风格:

  • type: 'capsule'(悬浮胶囊岛屿风格,当前默认)
    • 位于屏幕底部的悬空圆角 Dock 栏(rounded-[34px] + 柔和立体微阴影);
    • 配备带贝塞尔弹性曲线(cubic-bezier(0.25, 1, 0.5, 1))的滑块胶囊(Animated Slider Pill),切换时平滑穿梭;
    • 按下时具备 iOS 灵动触感反馈(整体微弹放大,松开回弹缩回);
    • 支持 glassEffect 开关(iOS 26+ 液态玻璃),完美适配亮色 / 暗黑主题与底部安全区。
  • type: 'default'(标准贴底底座风格)
    • 采用清晰的三层层叠结构(tabbar-bg 底板层 + tabbar-inner 图标层 + safe-area-bg 安全区层);
    • 全端 100% 支持立体凸起鼓包按钮(midButton,如居中 AI 交互按钮)、字体图标与小红点 / 数字徽标。
3. 单页面 TabBar 自动化脚手架与 Vite 插件

unibestX 将页面路由扫描与 TabBar 单页面调度深度结合,在 vite.config.ts 中通过专门的 tabbarViewsPlugin 实现全自动脚手架闭环:

// vite.config.ts
import tabbarViewsPlugin from './plugins/vite-plugin-tabbar-views';

export default defineConfig({
  plugins: [
    // 单页 TabBar 基础脚手架与视图组件辅助生成插件
    tabbarViewsPlugin({
      enabled: true,                       // 【总控开关】:默认 true
      configFile: 'src/tabbar/config.uts', // 【TabBar 配置文件路径】
      autoCreateViews: true,               // 【视图脚手架自动生成】:检测到缺失视图时自动按规范创建 views/*View.uvue
      syncNavbarConfig: true               // 【导航栏状态自动同步】:自动感知各 Tab 页面 definePage 的 hideNavbar / hideStatusBar
    }),
    // ... 其他插件
  ]
});
4. 自动化生成机制与开发工作流(VITE_TABBAR_MODE=4)

当 .env 中设置 VITE_TABBAR_MODE=4 且插件开启时,开发者只需要维护 src/tabbar/config.uts 一份配置文件,所有底层的调度容器与视图组件全由插件自动生成与热同步:

src/tabbar/config.uts (唯一样本源)
         │
         ├── 1. 自动生成调度容器 ──────> src/tabbar/components/TabViews.uvue
         │
         └── 2. 缺失视图时自动生成脚手架 ──> src/pages/*/views/*View.uvue

自动生成的文件与职责:

  1. 调度总容器(src/tabbar/components/TabViews.uvue)
    • 插件解析 config.uts 的 list 与 midButton,自动完成导入语句;
    • 自动生成 <TabContent :content-index="..."> 块,并自动感知各 Tab 页面的 definePage,若配置了 hideNavbar 或 hideStatusBar 会自动注入同步属性。
  2. 业务子视图脚手架(src/pages/<模块>/views/<模块>View.uvue)
    • 当在 config.uts 中添加了一个新的 Tab 项(例如 src/pages/order/order),若该目录下尚未存在 views/OrderView.uvue,插件会自动生成一份符合规范的基础组件;
    • 自动生成的组件预置了 UTS defineOptions 隔离、onTabShow 激活刷新钩子、onNavbarPullDownRefresh 自定义下拉刷新联动机制,开箱即用。

开发者新增 / 调整 Tab 的极简心智流程:

  • 新增 Tab
    1. 在 src/tabbar/config.uts 的 list 数组中添加一项(指定 text、icon、pagePath 等);
    2. 保存后,插件自动生成对应的 views/*View.uvue 脚手架,并自动更新 TabViews.uvue;
    3. 直接在生成的 views/*View.uvue 中编写业务代码,无需手写任何路由容器与挂载代码。
  • 中间鼓包按钮(midButton)按需启停
    • 启用鼓包:解开 midButton 注释,插件自动按居中索引插入并挂载 AiView;
    • 禁用鼓包:直接用 // 注释掉 midButton,插件自动清洗注释并从调度容器中剔除。

⚠️ midButton 跨端兼容性:官方原生底层在 微信小程序 / 鸿蒙 / iOS(Vapor) 端不支持 midButton,仅 Web 4.0+ 与 iOS(VDOM) / Android(VDOM) 支持。 若业务必须使用鼓包立体悬浮效果且需全端一致,请配置 VITE_TABBAR_MODE=2(自定义 TabBar 模式),组件层支持 100% 全端一致渲染。

5. 统一路由跳转与安全 API(src/tabbar)

模块唯一入口为 src/tabbar/index.uts(单层 export * 门面),内部实现位于 internal/,请勿绕过门面直接引用内部模块。

  • switchTabbar(url: string) — 全局统一 TabBar 跳转方法。单页面模式下直接切换索引,多页面模式下自动调度 switchTab 或 redirectTo(内置 250ms 节流锁,防止快速连击卡死)
  • onTabShow(index, callback, immediate?) — 监听特定 Tab 项激活显示,完美解决单页面模式下子视图没有原生 onShow 的问题(可在切换回该 Tab 时触发数据重新请求与刷新)
  • onTabPageShow(index, callback, immediate?) — 监听特定 Tab 页面显示(要求「页面可见」且「当前激活 Tab 命中」),是 onTabShow 的超集 —— 除切换 Tab 外,还覆盖 onTabShow 够不到的「页面回来了」:从子页面 navigateBack 返回、App 从后台回到前台。它同时修掉 onTabShow 的一个时序坑:在子页面里调 switchTabbar 时 curIdx 立刻变化,onTabShow 会在容器页仍不可见时提前回调,而 onTabPageShow 会抑制这次并推迟到页面真正返回时再补发一次
  • syncCurIdxByCurrentPage() — 自动从当前页面路由同步激活 Tab 项索引
  • notifyPageShow() / notifyPageHide() — 页面可见性桥接。模式 4 已在容器页 src/pages/index/index.uvue 的 onShow / onHide 中内置;模式 0-3 若也要「从子页面返回时触发」,在对应 Tab 页面的 onShow / onHide 里各加一行即可(完全未桥接时 onTabPageShow 自动退化为 onTabShow 的语义,不会静默失效)
  • safeHideNativeTabBar() — 全端安全隐藏原生底板,并在 H5 平台注入动态样式清除视口多余空白
  • initNativeMidButtonTap() — 仅在原生模式且配置 midButton 时自动注册监听,无需在页面中硬编码

主题切换(暗黑模式)

内置三种外观模式:auto(跟随系统)/ light(浅色)/ dark(深色)。入口位于「基础」页的主题切换卡片(src/pages/basic/components/ThemeSwitchCard.uvue),状态管理在 src/store/。

各端跟随机制:

  • App(Android / iOS / 鸿蒙):auto 模式监听 uni.onOsThemeChange 实时跟随系统深浅色;手动 light / dark 通过 uni.setAppTheme + uni.onAppThemeChange 生效。注意 Android 10+ / iOS 13+ 系统才支持深色模式。
  • H5:通过 prefers-color-scheme 媒体查询监听系统深浅色。
  • 微信小程序:读取宿主主题 hostTheme,auto 模式监听 uni.onHostThemeChange 跟随微信宿主主题。

颜色配置采用单源方案:

  • 根目录 theme.json 定义 light / dark 两套色板(导航栏、TabBar、页面背景等);
  • pages.json 通过 @ 变量引用(如 "navigationBarBackgroundColor": "@navigationBarBackgroundColor"),驱动原生导航栏 / TabBar / 页面背景;
  • 自定义组件(NavBar、TabBar、全局容器)通过 src/utils/theme/index.uts 的 getThemeTokens() 读取同一份色板,保证与原生配置一致。

💡 修改 light / dark 主题配色,请统一在根目录 theme.json 中配置(单源维护,pages.json 与自定义组件自动同步生效,勿在页面或组件中写死颜色)。

💡 全局导航栏如何跟随主题:uni-app X 没有「运行时全局 navbar 配置」API,原生导航栏样式属于编译期静态配置(pages.json 的 @变量)。运行时切换主题时,由 applyNavbarTheme() 同步(挂载在全局根包裹组件 App.ku.uvue 的 onShow 与主题监听上,每个页面切换都会触发):H5 直接修改 uni-page-head 的 DOM 样式(背景 / 文字 / 按钮色);微信小程序无 DOM,走官方 uni.setNavigationBarColor;App 端由 uni.setAppTheme 系统级切换,自动跟随。navigationStyle: custom 的页面没有 uni-page-head,H5 自动跳过。

[!IMPORTANT] 平台限制说明

  • 小程序原生导航栏背景色 navigationBarBackgroundColor 支持 @theme.json 变量,真机可正常随主题切换,但微信开发者工具模拟器可能无法正确预览深色效果,以真机效果为准(真机跟随微信「我 → 设置 → 通用 → 深色模式」)。
  • 微信小程序端 uni.setNavigationBarColor 的 frontColor 仅支持 #ffffff / #000000,自定义导航栏文字颜色请通过组件 props 传入(src/components/NavBar/NavBar.uvue)。

路由守卫

提供灵活的登录拦截策略:

  • 黑名单模式(默认):仅指定页面需要登录
  • 白名单模式:除指定页面外,全部需要登录
  • 支持登录后自动跳回原页面

相关文件:src/router/config.uts(策略配置)、src/router/interceptor.uts(跳转拦截)、src/router/toLoginPage.uts(登录页跳转)。

请求封装

基于 lime-request 封装的 HTTP 客户端(src/http/request.uts):

  • 自动携带 Token
  • 请求 / 响应拦截器
  • 多域名支持
  • 401 自动登出
  • 支持忽略认证的请求
  • 另有 src/http/stream.uts 提供 SSE / Chunk 流式请求能力

⚠️ 严禁自己写 uni.request —— 鉴权头、业务码判定、401 跳登录都在 src/http/request.uts 的拦截器里统一处理。

文件上传

基于原生 uni.uploadFile 统一封装的高性能跨端文件上传模块(src/utils/upload/index.uts):

  • 跨端原生适配:全端通用(App Android / iOS / HarmonyOS、微信小程序、H5)
  • 统一鉴权:自动从 TokenStore 注入 header.token(支持 ignoreAuth: true 跳过鉴权)
  • 智能路径拼接:支持传入完整 URL 或仅传入相对接口路径(如 /api/upload 自动与基础域名拼接)
  • 上传进度监听:支持 onProgress 进度回调
  • 智能响应解析:兼容 code: 200、code: "10000"、success: true、data: "url"、data: { url: "..." } 等多种后端返回格式,业务失败时自动提取错误信息

配置说明(通过 .env 环境变量):

在对应环境的 .env 文件(.env.development / .env.test / .env.production)中配置上传接口基础域名与路由路径:

VITE_UPLOAD_BASEURL=https://xxx.com                # 上传基础域名
VITE_UPLOAD_PATH=/gateway/user/sys/oss/upload/xxx  # 上传接口路由

底层会自动从 import.meta.env 读取当前环境的配置,无需改动源码。

调用示例:

import { uploadOssFile, uploadFile } from '@/src/utils/upload/index.uts';

// 1. 快捷上传图片到 OSS
uploadOssFile(filePath)
  .then((ossUrl: string) => {
    console.log('上传成功 OSS 地址:', ossUrl);
  })
  .catch((err: Error | null) => {
    uni.showToast({ title: err?.message ?? '上传失败', icon: 'none' });
  });

// 2. 自定义上传接口与进度监听
uploadFile({
  url: '/api/custom-upload', // 相对路径自动拼接 BaseURL,也可传完整 http(s) URL
  filePath,
  name: 'file',
  onProgress: (progress: number) => {
    console.log(`当前上传进度: ${progress}%`);
  }
});

状态管理

src/store/ 采用双模式自适应设计,由 src/store/index.uts 按平台条件编译自动路由:

src/store/index.uts  (门面:唯一转发层)
   │
   ├── vapor/  ── 官方 Pinia + pinia-plugin-persistedstate
   │     App 蒸汽模式(VUE3-VAPOR) / H5 / Web / 全部小程序平台
   │
   └── vdom/   ── x-pinia-s(UTS 原生强类型实现)
         未开启蒸汽模式的 App 原生端(如 Android VDOM)
  • AppStore — 主题色、语言设置
  • TokenStore — 支持单 Token 和双 Token(access + refresh)模式
  • UserStore — 用户信息管理
  • 内置持久化,全端复用 pinia-plugin-persistedstate

💡 推荐优先选用 Vapor 模式:可直接使用 Vue 官方 Pinia 组合式 API,无需繁琐的 UTS 类型约束与手工序列化 / 反序列化,并能直接复用官方持久化插件与成熟社区工具。

⚠️ 重导出红线:同一顶层符号(useAppStore / useTokenStore / useUserStore)只允许在 src/store/index.uts 这一层门面 export * 转发,层层转发会让 UTS 在 Android 端生成 useXxxStore__1 重名符号并导致运行期 NoSuchMethodError。详见该文件头部注释。

i18n 多语言

基于 lime-i18n 的国际化方案:

  • 内置中文(zh-CN)和英文(en-US)
  • 自动检测系统语言,也可通过 .env 的 VITE_DEFAULT_LOCALE 指定默认语言
  • 支持 VSCode i18n-ally 插件
  • 非 Vue 文件中也可通过 src/utils/i18n/index.uts 的 t() / $t() 使用翻译函数

Layout 布局

通过 plugins/uni-layouts-plugin.ts 实现:

  • 自动为页面包裹 Layout 组件
  • 内置 default / empty / navbar 三种布局,支持页面级别自定义布局
  • 可通过 layout: false 禁用布局

H5 容器化部署 (Docker & Nginx)

针对传统前端容器化打包臃肿及 uni-app X 依赖 HBuilderX CLI 编译的特殊性,项目定制了业界标准的 「宿主机构建 + Nginx:alpine 极简容器」 部署方案:

  • ⚡️ 秒级打包与极致轻量:镜像仅包含静态产物与 Nginx 运行时,体积仅约 25MB,打包过程 1~2 秒即可完成。
  • 🌍 原生多架构支持:基于 nginx:alpine,原生兼容 linux/amd64 与 Apple Silicon linux/arm64,开发机与云服务器均无转译损耗。
  • 🔄 动态环境变量反代:容器启动时,官方 entrypoint 自动利用 envsubst 读取 deploy/.env.test 或 deploy/.env.prod 中的 API_UPSTREAM 注入 Nginx,修改后端地址无需重打镜像。
  • 🛡️ 生产级 Web 保障:内置 Gzip 压缩加速、SPA Hash 路由 try_files 兜底、静态资源 /assets/ 30 天强缓存。
# 测试环境:一键切换环境 -> H5 编译 -> 构建 Docker 镜像 -> 启动容器(映射 8081)
pnpm docker:build:test && pnpm docker:up:test

# 生产环境:一键切换环境 -> H5 编译 -> 构建 Docker 镜像 -> 启动容器(映射 8080)
pnpm docker:build:prod && pnpm docker:up:prod

# 停止容器服务
pnpm docker:down

📖 详尽部署指南与服务器上线步骤请参阅 H5 端 Docker 部署手册。

代码规范与 Git 提交拦截 (Husky · Stylelint · Commitlint)

unibestX 引入了覆盖 JavaScript / UTS 强类型代码、SCSS / UVUE 样式以及 Git 提交日志 的完整工程化质检链路,把跨端平台崩溃隐患拦截在 Git 提交之前:

mermaid diagram

1. ESLint & UTS 平台专属规则插件 (plugins/eslint-plugin-uts.mjs)

针对 uni-app X 跨端原生编译对 UTS 类型与模板语法的严苛要求,内置 12 条专项规则:

  • 强类型红线:强制使用 type 禁止 interface(uts/no-interface 支持自动 --fix)、禁止 undefined、禁止 map.keys() 函数式调用;
  • 原生平台编译防护:严禁在模板 class 中使用 ! 修饰符(uts/uvue-no-important-modifier),防止 weapp-tailwindcss 生成包含 __weapp_tw_important__ 类名引发鸿蒙 ArkTS 编译器未知类报错;
  • VDOM 兼容性提示(warn):提示 <view> 误挂 color 文本颜色、原生不支持的 gap 与 space-*、font-mono 等差异。
2. Stylelint 样式规范 (stylelint.config.mjs)
  • 基于 stylelint-config-standard-scss 与 stylelint-config-standard-vue/scss(通过 postcss-html 解析 .uvue 中的 <style> 标签);
  • 原生放行 uni-app 特有尺寸单位(rpx、upx)及原生组件标签(page、view、scroll-view、list-view、uni-tabbar 等);
  • 完美兼容 Tailwind CSS v4 指令(@theme、@utility、@source、@apply 等);
  • 针对 App 原生渲染引擎关闭 inset 等简写强转,保证 top/bottom/left/right 显式声明不被破坏。
3. Husky + lint-staged 增量校验
  • 提交时触发 pre-commit 钩子,仅对暂存区变动文件执行校验与修复,秒级完成,免去全量扫描耗时;
  • 串行执行并抑制底噪,遇到错误时输出清晰中文横幅与精准行号定位。
4. Commitlint 提交信息中文校验

提交日志遵循 Conventional Commits 规范,格式为 <type>(<scope>): <subject>。未按规范书写时,提交会被拦截并输出友好中文说明:

类型说明示例
feat新增功能与特性git commit -m "feat(auth): 新增微信小程序一键授权登录"
fix修复缺陷或问题git commit -m "fix(popup): 修复鸿蒙端手势滑动关闭失效"
docs文档与注释变更git commit -m "docs: 更新 Docker 容器化部署指南"
style样式、代码格式调整(不影响功能)git commit -m "style: 调整个人中心卡片内边距"
refactor代码重构(非新增功能、非修 bug)git commit -m "refactor(http): 重构网络请求拦截器"
perf性能优化git commit -m "perf(list): 将长列表优化为 list-view 虚拟复用"
test增加或修改测试用例git commit -m "test(router): 补充登录拦截守卫测试用例"
build / ci构建系统、外部依赖或 CI 流水线调整git commit -m "build: 升级 Tailwind CSS 与 Vite 插件"
chore其他杂务、琐事配置变更git commit -m "chore: 更新 .gitignore 过滤规则"
5. 常用命令与跳过机制
  • 手动触发全量检查:

    pnpm lint:all        # 全量运行 ESLint + Stylelint 检查
    pnpm lint:fix        # 自动修复 ESLint 问题
    pnpm lint:style:fix  # 自动修复 Stylelint 问题
    
  • 临时跳过提交钩子(紧急情况):

    git commit -m "fix: 紧急修复线上问题" --no-verify
    

🙏 参考

本项目参考自 unibest,官网地址:unibest.tech/

📄 License

MIT

Copyright (c) 2026 HTwoO