TDesign 微信小程序组件库：98 个组件，19 秒构建出包

小程序做久了都会碰同一个问题：界面代码在重复。按钮的禁用态、单元格的右箭头、弹窗的遮罩、表单的校验提示，每个项目再写一遍，写完还得记住上次在哪儿踩过坑。微信内置组件只给了骨架，样式和交互全靠自己拼，拼到第三个小程序，你的 utils 里就住着一整个手写组件库。

TDesign 微信小程序组件库就是替掉这一摊东西的。它是腾讯设计体系 TDesign 的小程序端实现，标签统一 t- 前缀。我把 1.17.0 的构建产物数了一遍：98 个可注册组件、405 个 JS、127 个 WXML、128 个 WXSS、113 个 JSON，合计 1198 个文件、1.49MB。MIT 协议，可以改、可以商用、不用署名。

我在这台 Windows 11 上装依赖、走完整套 gulp 构建，出包 18.87 秒；又在一台 2 核 1.6GB 的 CentOS Stream 9 上重跑，37 秒出 1146 个文件，抽样的 JS / JSON / WXML 和 Windows 侧逐字节一致。官方演示的 34 个代码块用 miniprogram-simulate 逐块独立渲染，34/34 全部出图，拼成 4 个桌面页加 3 个手机页，0 报错。结论先给：源码路线能跑通，但装依赖那一步会连撞三个坑。它也不适合要跨端的人，后面单列。

它是什么，和原生手写差在哪

四种做法放一起看最清楚：

• 纯手写样式：一个按钮 60 行 WXSS，改主色要全项目搜色值
• 微信内置组件：button、input、picker 都有，禁用态、尺寸、加载态全要自己补
• TDesign 小程序组件库：把设计规范做进属性，theme、size、disabled 都是一个属性的事
• 跨端组件库：一套代码编到多个平台，代价是绑死某个框架和构建工具

98 个组件按目录数，日常场景基本铺满：按钮、图标、文本、链接、栅格打底，导航栏、标签栏、标签页、步骤条管导航，输入框、开关、复选框、单选框、滑块、步进器、评分、选择器、日期时间选择器、上传、日历管输入，单元格、折叠面板、图片、公告栏、徽标、头像、进度条、骨架屏、空状态、结果页管展示，消息提示、弹窗、弹出层、加载、抽屉、动作面板管反馈。

几个设计取向值得单独说：主题色改 CSS 变量（--td-brand-color 这一类），不覆盖类名；尺寸是 48 / 40 / 32 / 24 四档，按钮、图标、间距共用一套刻度；语言包内置，lang 在 zh_CN / zh_TW / en 之间切；属性名跟 TDesign 其他端对齐，PC 端写过的 theme、variant 到小程序端不用重学。

版本号 1.17.0。源码里另带一套 Vue 单文件组件版本，对应 uni-app 那条链路，那个方向我没测，本文数据只针对微信小程序端。

我的测试环境

• Windows：Windows 11，Node v24.21.0，npm 11.13.0，pnpm 11.11.0
• Linux：CentOS Stream 9，2 核 1.6GB，Node v22.23.4（机器原本没 node）
• 源码包：6.77MB 的 tar.gz，解开 5193 个文件的 monorepo
• 预编译包：361KB 的 tgz，1177 个文件
• 渲染链路：官方 miniprogram-simulate，每个演示块单独起进程

安装：Windows

三步，前两步都有坑。

1. 解开源码包，进目录装依赖：

tar -xzf tdesign-miniprogram-1.17.0.tar.gz
cd tdesign-miniprogram-tdesign-miniprogram-1.17.0
pnpm install

实测 228.9 秒，解析 2793 个包、写入 2705 个。项目自带 .npmrc 指向国内镜像，不用配源。用 pnpm 别用 npm，锁文件是 pnpm 格式。

2. 构建产物：

node node_modules/gulp/bin/gulp.js build --gulpfile script/gulpfile.dist.js

别用 pnpm run build，会直接退出 1，原因见后面第一个坑。上面这条是绕过它的写法，18.87 秒、退出码 0，产物落在 packages/tdesign-miniprogram/miniprogram_dist。

3. 想看演示，用源码里自带的 _example，在微信开发者工具里打开该目录直接编译。命令行环境没有开发者工具，我改用 miniprogram-simulate 做渲染验证。

安装：Linux

服务器没有图形界面，系统原本没 node，先装 22 系列（压缩包解开后把 bin 加进 PATH）：

tar -xf node-v22.23.4-linux-x64.tar.xz
export PATH=/tmp/node-v22.23.4-linux-x64/bin:$PATH
npm i -g pnpm

装依赖丢后台，别在前面等：

cd /tmp/tdtest && nohup pnpm install > install.log 2>&1 &
tail -f install.log

构建工具链单独装在一个目录（gulp、gulp-typescript、gulp-less 等 20 个包，705 个依赖，约 4 分钟），然后跑同一个任务：

NODE_ENV=production node node_modules/gulp/bin/gulp.js build --gulpfile script/gulpfile.dist.js

退出码 0，37 秒，产物 1146 个文件、1,657,696 字节，比 Windows 少 52 个——少的是 13 个 JS 和 18 个 .d.ts，因为精简工具链没装 workspace 全部类型依赖，TypeScript 报了 282 个 semantic error 就少 emit 了一部分。运行时需要的 js / wxml / wxss / json / wxs 一个不缺。

抽样哈希：button.js、button.json、button.wxml 两边都是 dccb35e9…、f8e841c3…、29abea82…，逐字节一致；button.wxss 两边不同（Windows ea32ecc7… 23718 字节 / Linux d716f64e… 23590 字节）。差异来自压缩链版本，Linux 侧这两个 WXSS 反而和官方预编译包逐字节一致。

接进自己的小程序项目

推荐直接用构建好的产物，不走 npm 构建。

1. 把 miniprogram_dist 整个目录拷到项目的 miniprogram_npm/tdesign-miniprogram/ 下
2. 页面或组件的 JSON 里声明用到的组件：

{
  "usingComponents": {
    "t-button": "tdesign-miniprogram/button/button",
    "t-cell": "tdesign-miniprogram/cell/cell",
    "t-toast": "tdesign-miniprogram/toast/toast"
  }
}

3. WXML 里直接写，属性按设计规范给：

<t-button theme="primary" size="large" bind:tap="onSave">保存</t-button>
<t-cell title="订单号" note="20261027001" hover arrow />

4. 消息提示这类要挂实例的组件，页面里先放容器再调方法：

import Toast from 'tdesign-miniprogram/toast/index';

Page({
  onSave() {
    Toast({ context: this, selector: '#t-toast', message: '已保存' });
  }
});

走 npm 那条路也行：npm i tdesign-miniprogram，再在开发者工具里点「工具 → 构建 npm」。但必须自己补一句 npm i tslib，原因见后面的坑。

源码构建和预编译包差在哪

很多人担心「自己构建会不会把库搞坏」，我做了逐字节比对：预编译包 1177 个文件全部能在构建产物里找到，其中 1078 个逐字节一致；99 个 .wxss 有字节差异，来自 less 与 gulp-clean-css 的版本差；JS、JSON、WXML、.d.ts 全部一致。构建产物比预编译包多 21 个 miniprogram_npm/ 提取产物。自己构建不改变行为，只是样式压缩结果可能差几十字节。

实测数据

• 依赖安装：Windows 228.9 秒（2793 包）；Linux 约 4 分钟（705 个构建依赖）
• 构建耗时：Windows 18.87 秒，Linux 37 秒，退出码都是 0
• 构建产物：Windows 1198 文件 / 1,566,625 字节；Linux 1146 文件 / 1,657,696 字节
• 产物构成：JS 405、.d.ts 392、WXSS 128、WXML 127、JSON 113、WXS 33
• 预编译包：1177 文件 / 1,512,547 字节
• 一致性比对：1078 / 1177 逐字节一致，99 个 WXSS 有差异
• 组件渲染：官方演示 34/34 块全部成功
• 静态页验收：7 个页面全部 HTTP 200，控制台报错 0，4xx/5xx 0
• 页面高度：桌面 2071 / 1435 / 2074 / 2012，手机端 3271 / 2286 / 2745
• 首页首请求：HTTP 200、498 毫秒，HTML 52,707 字节
• Node 侧导入：98 个组件里 95 个能直接 require
• 成品包：12,251,497 字节（11.68MB）、6859 个条目

界面长什么样

组件总览页，顶上四个数字就是这版的实际体量：98 个可用组件、1198 个构建产物文件、405 个编译后 JS、MIT 协议。

表单组件页，输入框、开关、复选框、单选框、滑块、步进器、评分、搜索、选择器排在一起，能看出同一套刻度和间距：

展示组件页，单元格、折叠面板、图片、公告栏、链接、标签页、分段控制器、空状态、结果页：

组件详情页最能说明问题：按钮的基础、尺寸、幽灵、禁用四种演示，下面铺开从 props.ts 生成的属性表，三十多个属性连默认值和说明一起列出来：

390 宽度下的同一页，手机上就是这个观感：

手机端的表单页，表单项在一屏里滚得动，间距没挤在一起：

需要说明一句：这些图是把官方演示块逐块渲染出来的静态页，不是真机截图。头像、图片这类要拉外链资源的组件只剩灰色占位框，图标字体没本地化时也会缺字形——这是渲染环境的限制，不是组件坏了。

三个真实的坑

第一个，pnpm run build 直接退出 1，跟代码无关。 报错是 ERR_PNPM_IGNORED_BUILDS，被点名的是 micromark。pnpm 在 run 之前做一次依赖状态检查，发现某个包的构建脚本被忽略就把它顶成整体失败。绕开 pnpm run 直接调 gulp 即可，第一次遇到的人八成会去翻 gulpfile，其实跟 gulp 没关系。

第二个，Node 20 及以上构建报 lib/mappings.wasm 找不到。 原文是 You must provide the URL of lib/mappings.wasm，来自 source-map@0.7.3。它在 read-wasm.js 里判断环境：看到全局有 fetch 就走浏览器分支，去拉一个根本不存在的 wasm 地址。Node 20 开始默认带 fetch，于是构建链里所有用到 source-map 的环节一起炸。解法是预加载一段脚本把全局 fetch 删掉：

delete globalThis.fetch;

node --require ./no-fetch.cjs node_modules/gulp/bin/gulp.js build --gulpfile script/gulpfile.dist.js

第三个，预编译包没有声明 tslib 依赖。 package.json 的 dependencies 是空对象，但产物里 405 个 JS 有 112 个 require('tslib')。按常规流程「构建 npm」之后，模拟器或真机会直接 module not found，报错指向组件内部，看起来像包坏了。补一句 npm i tslib 就好，但文档没写。

另外两个小的：图标字体走外链 CDN，离线环境要么本地化要么看着方块；miniprogram-simulate 对注册顺序敏感，同一进程里先渲染 A 再渲染 B，B 里 slot 的子组件会找不到，逐块独立进程渲染最稳。

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

适合：只做微信小程序、界面要看着像大厂做的；团队里没有专职 UI，界面靠一个人拼；想主题色一处改全站生效；用过 TDesign 的 Vue 或 React 端，想保持同一套视觉。

不适合：要一套代码同时出微信、支付宝、抖音的，这是微信端实现；完全不想碰 Node 构建链的，改主题改组件还得走一遍构建；项目里已经有自维护组件库的，两套视觉体系混用间距圆角会对不上；只做三五个页面的小程序，装组件库比手写还慢。

常见问题

源码获取

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