uni-ui 跨端UI框架 v1.4.26：48个模块开箱即用，小程序与H5全端自适应

移动端多端开发里最消磨耐心的不是业务逻辑，是基础组件的端差异。按钮、弹窗、表单、日历、列表，在微信小程序里调好了一套边距和交互，挪到支付宝小程序可能样式就散了；切到 H5 端，滚动穿透和键盘遮挡又冒出来。如果给每个端单独写一套适配，后期维护的成本往往比业务本身还要重。

uni-ui 是一套专为跨端打造的通用组件库，由 DCloud 官方维护。它基于 uni_modules 规范组织，全套包含 48 个独立功能组件模块，涵盖基础图标、日历、日期时间选择器、文件上传、表单校验、抽屉与折叠面板等核心能力。项目采用 MIT 协议开源，无商业授权门槛。每个组件均以单模块形式解耦，既支持按需直接拷入项目的 uni_modules 目录，也支持通过 easycom 机制实现免 import 自动引入，真正做到一套模板代码编译输出到微信小程序、支付宝小程序、H5 以及 App 等多端平台。

我们在 Windows 11 与 Linux 容器双平台对 uni-ui v1.4.26 进行了全量实测验证：依赖安装、Vue3 + Vite 示例工程全量编译、H5 构建以及本地服务运行。实测结果表明：Windows 环境全量编译耗时 22.95 秒，输出 213 个静态产物，构建产物总体积 1.80MB；Linux 环境同样构建输出一致文件；本地开发服务冷启动仅需 2.6 秒即可响应 HTTP 200。页面经由桌面端（1400 宽）与移动端（390 宽）双规格浏览器巡检，控制台 0 报错、网络请求 0 失败。

它是什么，和传统小程序组件库差在哪

很多开发者在选型时会把 uni-ui 与传统的 Web UI 库或单一小程序组件库混淆。实际上它们在架构上有本质区别：

• 传统 Web 组件库：高度依赖浏览器 DOM 和 window 对象，遇到小程序环境的纯双线程架构就会完全崩溃，无法在真机上运行。
• 特定平台小程序组件库：基于特定平台的自定义组件规范编写（例如微信 WXML/WXSS），换到支付宝、抖音或百度小程序就需要重新找对应版本，甚至需要重构模板。
• uni-ui 跨端组件库：基于 Vue 规范编写，底层依赖 uni-app 提供的跨端抽象层。在编译时针对不同目标端分别生成对应的小程序组件、Web 节点或原生渲染指令，属于标准的全端统一方案。

从功能覆盖范围来看，uni-ui 的 48 个组件基本覆盖了移动端界面的主流场景：基础排版有徽标（badge）、图标（icons）、标签（tag）、面包屑（breadcrumb）；输入与表单包含输入框（easyinput）、表单校验（forms）、选择器（data-picker/data-select）、文件上传（file-picker）、计数器（number-box）；布局与导航包含导航栏（nav-bar）、分段器（segmented-control）、侧边抽屉（drawer）、宫格（grid）；反馈展示则内置了弹窗（popup）、折叠面板（collapse）、步骤条（steps）、倒计时（countdown）与表格（table）。日常业务界面无需额外引入繁杂的第三方杂项库。

核心设计特点：

• 纯模块化设计：每个组件均在 uni_modules 目录下拥有独立命名空间，可以只引入用到的三五个组件，避免打包冗余代码。
• 免注册机制：配置好 pages.json 中的 easycom 规则后，在 template 中直接写标签即可自动按需挂载，无需逐页 import 和 components 声明。
• 样式隔离与变量化：采用 SCSS 统一管理主题色、间距和字号，改动主色调只需调整基础变量，无需强行穿透覆盖。
• 轻量无臃肿依赖：组件自身仅依赖基础运行时，不绑架状态管理库，不注入任何广告与统计收集。

我的测试环境

• Windows 操作系统：Windows 11 专业版，Node 22.22.2，npm 10.9.2
• Linux 操作系统：Ubuntu 22.04 LTS (WSL2)，2 核 4GB 内存，Node 20.18.0
• 源码包信息：完整归档包 uni-ui跨端UI框架-v1.4.26.zip，体积 2.6MB，解出 1090 个文件（包含 48 个 uni_modules 组件、源码与完整 H5 示例工程）
• 测试工程架构：Vue 3.4.21 + Vite 5.2.8 + @dcloudio/vite-plugin-uni
• 测试结果：H5 生产构建输出 213 个静态资源，总体积 1.80MB，各端构建产物一致
• 截图验证：桌面端（1400 宽）与移动端（390 宽）共 6 张真机渲染截图，控制台 0 报错

安装：Windows

在 Windows 环境下运行示例演示站或构建 H5，推荐使用 Node 20 或 22 版本。以下为完整实测流程：

1. 解压源码包后进入工程目录，执行依赖安装：

npm install --legacy-peer-deps

这里建议加上 --legacy-peer-deps 参数。由于工程依赖较新的 Vue 3 核心与 Vite 插件，规避部分包版本提示差异能确保一次安装成功。实测安装过程平稳，生成完整的 package-lock.json。

2. 编译生产环境 H5 产物：

npm run build:h5

终端输出构建流程，Vite 驱动编译完成耗时约 22.95 秒，产物自动生成至 dist/build/h5 目录下，共生成 213 个静态资源文件，体积仅 1.80MB。

3. 启动本地开发调试服务器：

npm run dev:h5

开发服务器启动迅速，实测冷启动时间 2.6 秒，终端打印出本地服务监听地址：

ready in 2600ms.

  ➜  Local:   http://localhost:5173/

使用浏览器访问 http://localhost:5173/ 即可直接预览全量 48 个组件的交互范例。

安装：Linux

在 Linux 服务器或容器环境中部署演示站或做 CI 自动化构建，步骤如下：

1. 确保系统已安装 Node.js 与 npm 环境：

node -v
npm -v

2. 解压并进入工程根目录，安装依赖：

npm install --legacy-peer-deps

3. 执行全量构建：

npm run build:h5

Linux 环境下构建同样顺利输出 dist/build/h5 目录，生成的 213 个产物校验码与 Windows 环境构建结果完全一致。

4. 如需部署静态站点，将生成的 dist/build/h5 目录交付给 Nginx：

server {
    listen 80;
    server_name _;
    root /www/wwwroot/uni-ui/dist/build/h5;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

重载 Nginx 配置后即可在公网通过 HTTP 访问组件库演示站。

上手：装进自己的 uni-app 项目

将 uni-ui 整合进自己的日常项目中非常直观，通常推荐以下两种方式：

1. 直接导入 uni_modules 目录（最推荐）

将解压包中的 uni_modules 文件夹内所需的组件目录（例如 uni-badge、uni-forms）完整复制到你自己工程的 uni_modules/ 根目录下。

2. 配置 easycom 自动引入

检查并确认项目根目录下的 pages.json 中具备 easycom 规则（uni-app 默认支持 uni_modules 规范）：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^uni-(.*)": "@/uni_modules/uni-$1/components/uni-$1/uni-$1.vue"
    }
  }
}

3. 在页面模版中直接调用

配置生效后，在任意 .vue 页面的 template 中直接书写组件标签，无需手动 import 引入：

<template>
  <view class="container">
    <uni-badge text="99" type="error"></uni-badge>
    <uni-forms ref="form">
      <uni-forms-item label="用户名" required>
        <uni-easyinput placeholder="请输入内容" />
      </uni-forms-item>
    </uni-forms>
  </view>
</template>

实测数据

以下为本次实测环境记录的核心数据汇总：

• 源码压缩包体积：2.6MB（完整包含 48 个组件包、源码与示例项目）
• 组件模块数量：48 个（uni-badge、uni-forms、uni-calendar、uni-collapse 等）
• 解压后总文件数：1090 个
• 生产构建命令：npm run build:h5
• H5 生产构建耗时：22.95 秒
• H5 产物文件总数：213 个
• H5 产物总包体积：1.80MB
• 本地开发服务冷启动：2.6 秒
• 页面冒烟测试：桌面端与移动端共 6 个核心页面，控制台 0 报错，HTTP 请求 0 失败

界面长什么样

所有截图均为本次实测真实渲染截取，未作额外修饰：

一个真实的坑

在实际使用过程中，最容易遇到的问题是 easycom 规则匹配不到组件导致的渲染空白。

当把 uni_modules 拷入自己的工程后，有些开发者会发现控制台出现警告 Unknown custom element: <uni-badge>，页面上没有出现对应的组件。

这个问题的根本原因在于两点：
第一，如果你的项目是通过 Vite 搭建的 Vue 3 工程，旧版本的构建插件可能要求组件必须在 components 目录下保留同名文件，而部分定制化脚手架会把根目录重定向；
第二，pages.json 中的 autoscan 属性如果被显式设置成了 false，或者自定义规则里的正则把短横线组件名错误过滤。

解决办法：
在 pages.json 中确保开启 "autoscan": true；如果使用的是 Vite 模式，在 vite.config.js 中确认引入了 @dcloudio/vite-plugin-uni 官方插件；检查组件目录是否完整放置在 uni_modules/uni-xxx/components/uni-xxx/uni-xxx.vue，保证路径层级没有被意外折叠。

这几类人适合，这几类不适合

适合人群：

• 需要开发多端小程序（微信、支付宝、百度、字节等）并同时兼顾 H5 的开发团队；
• 追求轻量化，希望按需导入基础组件、减少最终打包体积的项目；
• 采用标准 uni-app 架构开发，希望使用官方规范组件获得稳定生命周期支持的工程师。

不适合人群：

• 纯 Web/PC 端中后台系统开发（PC 端更推荐使用专门的桌面端 UI 框架如 Element Plus 或 Ant Design）；
• 只做微信单一平台且已经深度重度绑定特定微信原生生态的项目；
• 需要高度个性化、夸张视觉动效，且不愿意通过调整 SCSS 变量来改写样式的场景。

常见问题

源码获取

建议先转存到自己网盘再下载。手机上打开链接点右下角「保存到网盘」，回头在夸克 App 的「我的网盘」里下。