wot-design-uni v1.14.0：小程序组件库，一套代码跑多端

uni-app 项目里最耗时间的从来不是接口，是界面。按钮、弹窗、单元格、表单，微信端调好一套，转到支付宝小程序还得再试一遍；到了 H5 上间距又偏了，再修一遍。原生小程序组件库能省掉一半力气，可它们只认微信，一换端就歇，留给你的是一堆兼容补丁。

wot-design-uni 的显示名叫 Wot UI，定位很清楚：给 uni-app 写的移动端 UI 库。Vue3 组合式 API + TypeScript，组件统一 wd- 前缀，我在源码里清出 99 个 wd- 开头的组件目录，包自述写的是「70+ 高质量组件」。MIT 协议，2,300 多 Star。它挂在 uni_modules 插件体系上，一个目录拷进项目、pages.json 里加一条 easycom 规则，页面里就能写 <wd-button>——不换框架，也不动构建配置。

我在 Windows 11 和 CentOS Stream 9 上各跑了一遍完整流程：装依赖、构建 H5 演示站、把演示页逐个渲染截图。结论先给：Windows 上构建 30.63 秒出 472 个文件、2.56MB，Linux 上 160 秒出同样 472 个文件，两边产物逐字节相同。小程序端要微信开发者工具，这台机器没登那个账号，所以只验了 H5——这一点我写在明处，别把我没测的当成测过。另外它不适合三类人，后面单列。

它是什么，和原生小程序组件库差在哪

三类库放一起看最清楚：

• 原生小程序组件库：微信自定义组件形态，只能跑微信，换支付宝或抖音得换库或者自己改
• Web 端组件库：直接操作 DOM，小程序里根本跑不起来
• uni-app 插件组件库：一套 Vue 单文件组件，编译时分别产出小程序端和 H5 的代码，wot-design-uni 属于这一类

覆盖面上，我按源码目录逐个列过：按钮、图标、单元格、栅格布局打底；导航有导航栏、标签栏、标签页、侧边栏、索引栏；数据输入最重，表单、输入框、数字键盘、选择器、日期时间选择器、日历、上传、图片裁剪、签名板、滑块验证都在；反馈类有消息提示、弹窗、通知条、加载、骨架屏；展示类有卡片、表格、步骤条、倒计时、水印、轮播。日常移动端界面九成能拼出来。

几个设计取向值得单独说：

• 暗黑模式是内置的，不用自己再写一套配色
• 国际化内置 15 种语言包，切换靠 wd-config-provider 包住页面
• 主题定制走 CSS 变量，改色不用覆盖组件类名
• 插件声明里写明不采集数据、不申请权限

版本号是 1.14.0。组件前缀 wd- 有个副作用：如果你项目里已经有同前缀的组件，easycom 规则会打架，得改成自定义前缀那条路。

我的测试环境

• Windows：Windows 11，Node 22.22.2，pnpm 11.11.0
• Linux：CentOS Stream 9，2 核 1.6GB，香港节点，面板 Web 终端，Node 20.19.1 + pnpm 9.2.0
• 源码归档：14.9MB 的 tar.gz，解出 1021 个文件、247 个目录
• 测试端：H5 演示站（小程序端没测，原因见上）
• 截图：桌面 1400 宽、手机 390 宽，共 8 张，正文里的图都是我这台机器跑出来截的

安装：Windows

三步，其中两步有坑。

1. 解压后进目录，装依赖：

$env:HUSKY = "0"
pnpm install

HUSKY=0 不能省。项目的 prepare 脚本是 husky install，源码包不是 git 工作区，这一步会直接报错中断安装。实测装完 1590 个包，耗时 3 分 14 秒，锁文件命中、182 个包复用缓存。

2. 构建 H5 演示站：

pnpm build:h5

输出 DONE Build complete.，30.63 秒，产物落在 dist/build/h5，472 个文件、2,681,947 字节。

3. 想看效果就起开发服务器：

pnpm dev:h5

ready in 4576 ms，http://localhost:5173/ 返回 200，改代码热更新。

另一个坑：只能用 pnpm。 preinstall 挂的是 npx only-allow pnpm，packageManager 写死 pnpm@9.2.0，用 npm 或 yarn 会直接被拒装。省事的话先 corepack enable 再 corepack prepare pnpm@9.2.0 --activate。项目自带 .npmrc 指向国内镜像，不用自己再配源。

安装：Linux

服务器没有图形界面，全程命令行。Node 版本按项目根目录 .nvmrc 里写的来，是 20 系列——用 22 也能装，但锁文件是按 20 生成的，别给自己找麻烦：

export PATH=/usr/local/node-v20.19.1-linux-x64/bin:$PATH
npm i -g pnpm@9.2.0
cd /tmp/wottest && HUSKY=0 pnpm install

这台是 2 核 1.6GB 的机器，pnpm install 跑了 1012 秒（16 分 51.8 秒），比 Windows 上的 3 分 14 秒慢了五倍。别在前台等，一律丢后台再回来看日志：

nohup bash setup.sh > /tmp/wottest/setup.log 2>&1 &
tail -f /tmp/wottest/setup.log

构建同样 160 秒，比 Windows 的 30.63 秒慢得多，产物是 472 个文件。起个静态服务就能看：

cd dist/build/h5 && python3 -m http.server 18080

首页返回 200，耗时 0.0076 秒，index.html 1138 字节。

更值得看的是跨平台一致性——我把两边的产物做了逐字节比对：

• 文件数：Windows 472 / Linux 472
• 文件名清单按 LC_ALL=C 排序后取 MD5：两边都是 6aba40e0f2ce808f96156ff1552a2451
• 去掉预压缩的 .gz 后：两边都是 271 个文件、2,095,507 字节
• index.html 的 MD5：两边都是 331a1d6510ac8e9f2e4ac57d487f3b46

也就是说，这套库的构建结果跟平台、Node 小版本没关系，只跟依赖锁文件有关。团队里有人用 Mac、有人用 Windows，不会出现「我这儿好的」那种扯皮。

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

推荐拷目录这条路，不装 npm 包：

1. 把 uni_modules/wot-design-uni 整个目录拷到项目的 src/uni_modules/（Vite 模板）或项目根的 uni_modules/ 下
2. pages.json 里配 easycom，让组件按需自动引入：

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

3. 页面里直接用，不需要 import、也不需要注册 components：

<wd-button type="primary" @click="onSave">保存</wd-button>
<wd-toast ref="toast" />

4. 改主题色，覆盖 CSS 变量就行，不用碰组件源码：

page {
  --wot-color-theme: #1e6fff;
  --wot-color-success: #12b76a;
}

想省掉第一步可以走 npm：pnpm i wot-design-uni，easycom 规则里的路径写成 "wot-design-uni/components/wd-$1/wd-$1.vue" 即可，两种方式路径一样。

实测数据

• 依赖安装：Windows 3 分 14.2 秒（1590 包）；Linux 1012 秒
• H5 构建：Windows 30.63 秒；Linux 160 秒
• 构建产物：472 个文件、2,681,947 字节（2.56MB），其中 js 144、css 118、预压缩 gz 201、png 6、ttf 1、ico 1、html 1
• 开发服务器：ready in 4576 ms，首页 200
• 跨平台比对：文件数、文件名清单 MD5、非 gz 字节数、index.html MD5 四项全一致
• 静态服务：首页 200 / 0.0076 秒（Linux 侧）
• 成品包：18,047,401 字节、1875 个条目、sha256 4ad74a1227aa095aff1daaffb809f4730e8f62bfc7656413b882bfb8d22c27c6
• 成品包解压：4.23 秒解出 1875 个文件、370 个目录，13 项关键路径一个不缺，中文名无乱码
• 包内静态服务实跑：首页 200、80 个组件入口；按钮页渲染出 76 个按钮节点；控制台报错 0、页面异常 0、失败请求 0
• 直链扫描：包内 1875 个文件全量扫过，直取型下载地址 0 命中

界面长什么样

演示站首页按「基础 / 导航 / 数据输入 / 反馈 / 数据展示」五类收口，顶部写着版本号 1.14.0：

按钮是最常用的一个，基础/成功/信息/警告/危险五种状态，禁用、幽灵、细边框、大小、加载中、块状、图标按钮都给了示例，最后一屏还是 Material Design 3 的投影样式：

表单页面能看出组件的精细度，表单项、校验、标签宽度、只读状态都是独立属性：

弹出层支持顶部、右侧、底部、左侧四个方向，还有锁定滚动、禁用遮罩点击、底部安全区、嵌套弹窗这些细节开关：

关于页里能看到语言切换入口，当前语言显示「中文」，说明国际化不是摆设：

390 宽度下的首页，手机上就是这个观感，底部标签栏和组件分类都还在：

三个真实的坑

第一个，静态服务器并发拒连会让你误判成构建坏了。

python -m http.server 的 request_queue_size 默认只有 5，手机视口下表单页一次并发拉几十个 chunk，直接 ERR_CONNECTION_REFUSED，页面正文显示 uni.async.error。最要命的是 HTTP 日志里全是 200，你会以为构建产物有问题，去翻 Vite 配置。换成线程版并抬高队列就好了：

class Handler(SimpleHTTPRequestHandler):
    pass

class Server(socketserver.ThreadingTCPServer):
    request_queue_size = 256

Server(("0.0.0.0", 18080), Handler).serve_forever()

改完 0 报错。这条不只对 wot-design-uni 成立，任何 Vite 产物在本地起静态服务都会踩。

第二个，H5 里 wd-button 不渲染成 <button>。

我拿自动化去点「弹出层」那个触发按钮，get_by_text 怎么都点不动。翻了结构才明白：wd-button 在 H5 里是个 div 外壳，选 button 标签当然找不到；真正的触发器是 wd-cell 单元格。要稳稳命中就选 .wd-cell 再配文本过滤。写测试脚本、做页面自动化验收的时候，这条会直接卡你一晚上。

第三个，构建好的 H5 站点不能双击 index.html。

Vite 产物是 ES 模块，file:// 协议下 CSS 和 JS 全被 CORS 拦掉，页面一片空白，控制台四条 ERR_FAILED，标题还在但 body 是空的。必须起本地 http 服务。成品包里我因此带了一个零依赖的 Node 静态服务和一个启动脚本，双击那个脚本就行，别去点 index.html。

另外两个小的：prepare 的 husky install 在非 git 目录会失败（HUSKY=0 解决）；Linux 上装依赖要 17 分钟，前台跑一定会等到以为卡死。

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

适合：

• 正在写 uni-app，要一套代码同时出微信小程序和 H5 的
• 团队里没有专职 UI，界面靠一个人拼起来的
• 需要暗黑模式和国际化，又不想自己造这两块的
• 从原生小程序迁移到 uni-app，界面想尽量少改的

不适合：

• 纯微信原生小程序项目。用原生组件库更直接，多引一层 uni-app 没意义
• Vue2 项目。这套是 Vue3 + TS 写的，peerDependencies 要求 vue >= 3.2.47
• 要求像素级还原设计稿的。CSS 变量能改色，改布局还得覆盖组件样式，不如自己写
• 只做一个静态页面、连表单都没有的。装个组件库的收益还不够折腾

常见问题

源码获取

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