[](https://github.com/cq112233/unibestX) [   [](https://vitest.dev/) [](https://www.typescriptlang.org/)
`unibestX` 由 **`uni-app X` + `Vue3` + `UTS` + `Vite5` + `Tailwind CSS` + `z-paging-x`** 构成，采用下一代 uni-app 原生开发技术栈，通过 `HBuilderX` 一键运行到 **Android / iOS / 鸿蒙 / H5 / 微信小程序 / 支付宝小程序** 六大平台。 内置 `自定义 TabBar`、`Layout 布局`、`request-bestX 请求与状态机引擎`、`登录拦截`、`路由守卫`、`Tailwind CSS`、`i18n 多语言`、`主题切换`、`沙盒极速调试` 等基础能力，并提供 `代码提示`、`自动格式化`、`统一配置` 等辅助功能，让你编写 `uni-app X` 拥有 `best` 体验。 🤖 **AI 原生开发模板**：项目自带 **`unibestX-skill`**（「1 个入口 + 8 个分册」的 uni-app X / UTS 规范知识库），Claude Code、Codex 等 AI Agent 克隆即可直接按项目规范写代码、生成页面骨架、自动排查跨端编译报错；运行时亦内置 **AI 对话页**与 **SSE / Chunk 跨端流式传输**能力。 | 📖 官方文档 | 🐙 GitHub | 🍊 Gitee 镜像 | | :---: | :---: | :---: | | [cq112233.github.io/unibestX/docs](https://cq112233.github.io/unibestX/docs/) | [cq112233/unibestX](https://github.com/cq112233/unibestX) | [htwoO-cq/uni-best-x](https://gitee.com/htwoO-cq/uni-best-x) | --- ## 🚀 快速开始 ### 1. 创建 / 克隆项目 ```bash # 交互式创建（推荐） pnpm create unibestx my-app # 或免安装直接运行 npx create-unibestx my-app # 或通过 degit 快速创建 npx degit cq112233/unibestX my-project ``` ### 2. 填写 AppID 项目内自带的 AppID 仅用于演示，**请自行申请并替换为你自己的**： | 平台 | 申请入口 | 填写位置 | | :--- | :--- | :--- | | App（Android / iOS / 鸿蒙） | [DCloud 开发者中心](https://dev.dcloud.net.cn/) → 创建应用 | [manifest.json](manifest.json) 的顶层 `appid` | | 微信小程序 | [微信公众平台](https://mp.weixin.qq.com/) | [manifest.json](manifest.json) 的 `mp-weixin.appid` | ### 3. 安装依赖 ```bash pnpm install ``` ### 4. 运行项目 ```bash pnpm dev:web # 运行到 H5 / Web 端 pnpm dev:app-android # 运行到 Android 原生端 pnpm dev:app-ios # 运行到 iOS 模拟器（需 macOS + Xcode） pnpm dev:app-harmony # 运行到鸿蒙原生端（需 DevEco Studio） pnpm dev:mp-weixin # 运行到微信小程序 pnpm dev:mp-alipay # 运行到支付宝小程序 ``` ### 5. 打包与发布 ```bash # 打包 H5，产物输出到 unpackage/dist/build/web pnpm build:h5 # 测试环境打包 pnpm build:test ``` --- ## ✨ 特性 - 🚀 **uni-app X（Vapor 默认 + VDOM 兼容）** — 默认启用 **Vapor 蒸汽模式**（无虚拟 DOM 高性能原生渲染），同时全面兼容传统 VDOM 模式 - 💪 **Vue3 + Vite5** — 最新前端技术栈，极速开发体验 - 🎨 **Tailwind CSS** — 原子化 CSS 引擎（v4 + weapp-tailwindcss），全端通用 - 📦 **多分支 UI 选型** — `main` 分支为**无 UI 库纯净基线**；另有 `uniX-rice-ui`（Rice UI）和 `uniX-uview-ultra` 分支 - 📜 **z-paging-x** — 强大的分页列表组件 - 🏝️ **多策略 TabBar 体系** — 5 种运行策略 + 2 种视觉形态 - ⚡ **沙盒独立调试模式** — 大型项目本地开发只编译当前页面，秒级热更新 - 🔧 **Pinia 持久化** — Vapor 走官方 Pinia，VDOM 走 `x-pinia-s` - 🌐 **i18n 多语言** — 内置中英文切换 - 🛡️ **路由守卫** — 黑名单／白名单策略，灵活的登录拦截 - 🌈 **动态主题** — `theme.json` 单源色板 - 🧠 **request-bestX 请求与状态机引擎** — Axios 风格拦截器、GET 并发去重、TTL 缓存、useQuery/useMutation 声明式状态机、SSE 流式传输 - 🧬 **OpenAPI 强类型生成** — `pnpm api:gen` 一键生成 UTS 强类型接口 - 🐳 **H5 Docker 极速部署** — 宿主机构建 + Nginx:alpine 轻量容器 - 🧪 **完整单元测试体系** — Vitest + @vue/test-utils + happy-dom - 🤖 **AI 原生开发模板** — 内置 unibestX-skill 知识库，AI Agent 可直接按规范写代码 --- ## 📁 项目结构 ``` unibestX/ ├── src/ # 源代码目录 │ ├── api/ # API 请求模块 │ ├── components/ # 公共业务组件 │ ├── config/ # 全局配置中心 │ ├── http/ # 业务网络层 │ ├── i18n/ # 国际化多语言 │ ├── layouts/ # 页面布局模板 │ ├── pages/ # 主包页面（TabBar 页面） │ ├── router/ # 业务路由层 │ ├── store/ # 状态管理（双模式自适应） │ ├── sub/ # 应用分包页面 │ ├── tabbar/ # 底部 TabBar 体系 │ ├── theme/ # 主题令牌 │ └── utils/ # 基础工具模块 ├── uni_modules/ # uni-app X 扩展插件模块 │ ├── request-bestX/ # 跨端 HTTP 请求与状态机引擎 │ ├── route-bestX/ # 极简高性能跨端路由引擎 │ ├── z-paging-x/ # 分页组件 │ └── ... ├── plugins/ # Vite 构建插件 ├── scripts/ # 构建、环境与质量脚本 ├── tests/ # 自动化测试目录 └── docs/ # VitePress 文档站 ``` --- ## ⚙️ 环境要求 | 依赖 | 版本要求 | | :--- | :--- | | Node | `^22.22.2` | | pnpm | >= 10.0.0 | | HBuilderX | **5.26 及以上** | | Vue Official | >= 2.1.10 | | TypeScript | >= 5.0 | | JDK | >= 17（Android 平台） | --- ## 📦 推荐的 UI 组件库 | 组件库 | 推荐分支 | 说明 | | :--- | :--- | :--- | | **Rice UI**（强烈推荐） | `uniX-rice-ui` 分支 | 专为 uni-app X 打造，完美支持 Vapor 与 VDOM 模式无缝切换 | | **uview-ultra** | `uniX-uview-ultra` 分支 | 专为 uni-app X 打造的 UI 库 | | **无 UI 库（纯净基线）** | `main` 分支（默认） | 原生组件 + Tailwind CSS | --- ## 🧩 核心功能说明 ### 环境变量配置（`.env`） 项目的环境配置采用 **「公用 + 按环境拆分」** 的四文件结构： | 文件 | 用途 | | :--- | :--- | | `.env` | 公用变量，所有环境都会加载 | | `.env.development` | 开发环境 | | `.env.test` | 测试环境 | | `.env.production` | 生产环境 | ### 页面路由与配置 (uni-pages) 项目内置自动文件路由插件 **`vite-plugin-uni-pages`**，自动扫描 `src/pages` 和 `src/sub` 目录生成路由配置。 ### 状态管理 `src/store/` 采用**双模式自适应**设计： - **Vapor 模式**：官方 Pinia + pinia-plugin-persistedstate - **VDOM 模式**：x-pinia-s ### 请求封装 基于 `request-bestX` 的跨端 HTTP 请求封装： - Axios 风格拦截器 - GET 请求并发去重 - TTL 内存缓存 - useQuery / useMutation 声明式状态机 - SSE 流式传输 --- ## 📖 常用脚本 ```bash pnpm dev:web # 运行到 H5 pnpm dev:app-android # 运行到 Android pnpm build:h5 # 打包 H5 pnpm api:gen # 生成 OpenAPI 强类型接口 pnpm manifest # 生成 manifest.json pnpm test # 运行单元测试 pnpm typecheck # 严格类型检查 pnpm lint # ESLint 检查 pnpm docker:build:prod # 构建 Docker 镜像 ``` --- ## 🔧 技术栈详情 | 类别 | 技术 | | :--- | :--- | | 框架 | uni-app X（Vapor 模式默认开启） | | 语言 | UTS + TypeScript | | 前端框架 | Vue 3 (Composition API) | | 构建工具 | Vite 5 | | CSS 引擎 | Tailwind CSS v4 | | 状态管理 | Pinia / x-pinia-s | | HTTP 请求 | request-bestX | | 国际化 | lime-i18n | | 单元测试 | Vitest | --- ## ⚠️ UTS 开发注意事项 1. **文件扩展名**：使用 `.uts`（逻辑代码）和 `.uvue`（页面/组件） 2. **类型系统**：UTS 不支持 `undefined`，使用 `null`；使用 `==` 而非 `===` 3. **禁止使用 `interface`**：定义类型时一律使用 `type` 4. **CSS 限制**：部分 CSS 属性在原生平台不支持 5. **Android 端语法最严**：Android 编译器校验最严格，通过则其他平台通常无问题 --- ## 📄 License [MIT](https://opensource.org/license/mit/) Copyright (c) 2026 HTwoO --- ## 💬 联系 & 交流 - 微信：`cq_81894`（备注说明来意） - QQ 技术交流群：**983313908** --- 如果项目对您有帮助，请帮忙点个 **Star ⭐** 支持一下！您的鼓励是作者持续维护的动力！