前阵子在一个原生小程序项目里接入 TDesignnpm install tdesign-miniprogram这一步走得非常顺畅依赖装完我也没多想直接打开微信开发者工具点了一下「工具 - 构建 npm」。结果控制台立刻弹出一行红字NPM packages not found。说实话当时第一反应是装错包了但反复确认了好几遍包名没问题node_modules 下面也确实有 tdesign-miniprogram 目录。后面花了大半天把整个 npm 构建链路从头到尾捋了一遍才算彻底搞明白这个报错背后真正的原因。如果你也在接入 TDesign 时被 NPM packages not found 卡住或者单纯想把小程序里 npm 包的构建机制弄明白这份记录应该能帮你省下不少时间。1. 小程序为什么认不出 node_modules先搞懂构建机制1.1 小程序没有 Web 端的运行时依赖解析在 Web 项目里代码中 import 一个包最终会由打包工具分析依赖树并打进 bundle。小程序不是这个逻辑。小程序运行环境里根本没有 node_modules 的概念你写的 require 或者组件路径tdesign-miniprogram/button/button在运行时都不可能去 node_modules 里找文件它只会去项目里一个固定的目录找——默认是根目录下的 miniprogram_npm。微信开发者工具里的「构建 npm」做的是什么事你可以把它理解成一道搬运工序工具扫描 package.json 里声明的依赖进入 node_modules 找到对应包读取包内 package.json 的 miniprogram 字段指向的源码目录把整份目录原样拷贝到 miniprogram_npm 下同时改写包内部的相对路径让组件之间互相 require 时不会再去依赖 node_modules。也就是说npm 包必须经过构建这一步才可能被小程序运行时识别。这就是许多新手容易懵的地方明明 npm install 成功了package.json 里依赖也写了但页面里使用组件就是报错。原因不是包不存在而是包还没有被搬运到小程序能识别的目录里。1.2 NPM packages not found 到底在说什么NPM packages not found 翻译成大白话就是构建工具开始干活了但它在 package.json、node_modules、miniprogramNpmDistDir 这几个环节里断了链找不到可以构建的 npm 包源。这里要特别注意实际使用中报错分两种场景排查方向完全不一样点击「构建 npm」后立刻报错说明工具没有扫描到任何可用的包。问题大概率出在包本身不是小程序包、package.json 位置不对、npm 开关没打开或者 packNpmManually 配置错误。构建 npm 时没报错但编译页面时提示某个组件 not found。这种情况是 miniprogram_npm 目录里没有对应组件或者说 usingComponents 的路径写错了。很多帖子里把这两种情况混在一起来讲导致排查方向很容易跑偏。提示如果页面编译报错里带的是NPM packages not found这个原文先看一眼资源管理器里有没有生成 miniprogram_npm 目录。目录不存在说明构建步骤本身就没成功目录存在但组件仍然找不到那才是路径或包内部结构的问题。2. NPM packages not found 排查链路六个检查点逐个过这一章把实际排查的过程按顺序整理出来。建议你也按这个顺序来每改一处就先验证再改下一处避免瞎折腾。2.1 检查点一装的是不是 tdesign-miniprogram而不是 tdesign先别急着操作开发者工具打开 package.json看 dependencies 里写的到底是什么。TDesign 有 Web 版、Vue 版、React 版、小程序版小程序版的 npm 包名是tdesign-miniprogram。如果你不小心装成了tdesign那实际引入的是 Web 组件库小程序运行时跑不起来而且这类包大概率没有 miniprogram 字段构建 npm 时工具扫描不到任何可用的包直接就报 NPM packages not found。验证方法很简单打开node_modules/tdesign-miniprogram/package.json看里面有没有一行miniprogram字段。有说明这个包是面向小程序打包过的没有说明包本身就不是小程序组件库。2.2 检查点二项目里有没有 package.json和工具打开的是不是同一个目录构建 npm 的前提是项目根目录有 package.json没有就自己在根目录执行npm init。这里的关键问题是工具打开的根目录到底指哪里。原生小程序项目里app.json 在哪一层project.config.json 的 miniprogramRoot 就指向哪一层package.json 也应该在这一层。如果 miniprogramRoot 是空或者 ./那 package.json 放根目录没毛病。如果工具打开的项目根目录在更外层package.json 被放在了 miniprogram 子目录里那就必须通过 packNpmManually 手动告诉工具 package.json 在哪。这个不懂得配后面就容易一直撞墙。2.3 检查点三packNpmManually 是否配置正确很多项目不是标准的根目录即小程序根目录结构而是这种project-root/ ├─ package.json ├─ project.config.json └─ miniprogram/ ├─ app.js ├─ app.json └─ pages/这种结构下project.config.json 里 miniprogramRoot 指向 ./miniprogram而 package.json 在根目录。如果不做任何配置工具会跑到 miniprogram 目录里找 package.json找不到自然就报 NPM packages not found。解决办法是在 project.config.json 的 setting 里配置 packNpmManually 和 packNpmRelationList{ miniprogramRoot: ./miniprogram/, setting: { packNpmManually: true, packNpmRelationList: [ { packageJsonPath: ./package.json, miniprogramNpmDistDir: ./miniprogram/ } ] } }packageJsonPath告诉构建工具去哪个位置找 package.json。miniprogramNpmDistDir构建出来的 miniprogram_npm 放到哪个目录必须和你实际的小程序根目录一致。如果项目没有子目录app.json 就在根目录那 miniprogramNpmDistDir 直接写 ./ 就行。我最早就是在这里栽的项目结构带了一层 miniprogram 子目录packNpmRelationList 没配工具每次都在子目录里找 package.json结果折腾了很长时间才发现是路径配置的问题。2.4 检查点四本地设置里的使用npm模块开关在项目打开的开发者工具里点「详情 - 本地设置」找到「使用npm模块」开关确认它是勾选状态。这个开关在老版本里是 npm 构建的必要前置条件没有开启就点构建 npm即使其他配置全对也会提示找不到包。新版本工具里它默认是开的但有些从同事那里 clone 来的项目、或者本地配置和项目配置分离的场景下可能被关掉了。勾选之后建议把项目整个关掉重新打开一次再点构建 npm。这一步虽然是基础操作但很多人就是在这里疏忽了。2.5 检查点五node_modules 是不是 pnpm 装的这个坑容易被忽略。微信开发者工具对 pnpm 创建的符号链接结构支持有限。pnpm 安装依赖后node_modules 里是一堆软链工具扫描依赖时经常解析不到真实的包目录结果就是包明明装好了构建 npm 却一直说找不到包报 NPM packages not found。我在一个 monorepo 风格的项目里遇到过一次最后换回 npm install 重装依赖问题立刻消失。如果你是用 pnpm 在管理工程建议在小程序工程目录里单独用 npm 初始化一份依赖或者至少在小程序这一层用 npm 安装组件库不要直接复用 pnpm 的 node_modules。2.6 检查点六构建路径和工具版本剩下的两类问题比较玄学。一类是项目路径带中文或者空格老版本的构建工具在这种路径下解析包路径会出错从而报 NPM packages not found。现在虽然修复了不少但如果你怎么都排查不出来可以试试把项目拷贝到全英文路径下再构建一次花不了几分钟。另一类是微信开发者工具版本太旧。npm 构建能力一直在迭代不少历史 bug 都是在新版修复的。遇到怎么都说不通的问题先把工具升级到最新稳定版然后工具栏 - 清缓存 - 清除全部缓存关掉项目重新打开再走一遍构建流程。3. TDesign 最小可运行配置从安装到页面渲染3.1 正确的安装命令与依赖声明确认构建工具没问题之后剩下的就是 TDesign 本身的接入。TDesign 微信小程序版的最小接入步骤如下先在小程序根目录生成 package.json 并安装依赖npm init -y npm i tdesign-miniprogram -S --production这里有两个容易被忽视的点。第一必须加--production。加了这个参数npm 只会安装 dependencies 里的正式依赖devDependencies 里的内容不会被打包进 miniprogram_npm可有效控制小程序包体积。第二安装完成后看一下 package.json确保 tdesign-miniprogram 出现在 dependencies 下面而不是 devDependencies。如果出现在 devDependencies 里构建 npm 时工具默认不会处理它组件照样引入不了。3.2 project.config.json 推荐配置如果你和我一样用的是单目录原生小程序结构app.json 和 package.json 同层可以直接采用下面这套配置能省掉后面很多判断{ miniprogramRoot: ./, setting: { es6: true, postcss: true, minified: true, packNpmManually: true, packNpmRelationList: [ { packageJsonPath: ./package.json, miniprogramNpmDistDir: ./ } ] } }配置保存后重新打开项目再点「工具 - 构建npm」。正常情况下控制台会输出构建成功项目里多出miniprogram_npm/tdesign-miniprogram目录。提示如果构建成功但 miniprogram_npm 里只有一个空的 tdesign-miniprogram 目录说明工具读到了包但包内 miniprogram 字段指向的源码目录不对。打开 node_modules/tdesign-miniprogram/package.json 检查一下 miniprogram 字段的路径确认它实际指向的目录下有没有组件文件。3.3 注册组件的路径到底怎么写TDesign 官方文档给出的使用方式是在 app.json 里全局注册比如{ usingComponents: { t-button: tdesign-miniprogram/button/button, t-icon: tdesign-miniprogram/icon/icon } }注意这个路径写法是有讲究的。它省略了miniprogram_npm前缀也省略了node_modules前缀直接以包名tdesign-miniprogram开头。工具在编译时会自动把这种写法映射到miniprogram_npm/tdesign-miniprogram/button/button。如果你写成miniprogram_npm/tdesign-miniprogram/button/button有一部分项目也能生效但官方并不推荐因为一旦重新构建或者换了构建目录配置这种硬编码路径很容易断。实际操作时我建议只在用到组件的页面 json 里注册或者全局只注册高频基础组件。TDesign 全家桶有几十个组件全量全局注册会让主包体积膨胀很快。注册完之后在 wxml 里直接使用t-button typeprimary sizelarge登录/t-button3.4 app.json 里要删除 style: v2这一步非常容易漏。微信小程序默认工程里 app.json 通常有style: v2配置v2 样式会影响部分 TDesign 组件的表现比如按钮内边距不正确、导航栏偏移、单元格高度异常。TDesign 官方文档明确建议把 app.json 里的style: v2删掉。删除后需要清缓存重新编译一次很多组件明明引入成功但长得不对劲的问题都是这个细节引起的。删除之后 app.json 大概长这样{ pages: [pages/index/index], window: { navigationBarTitleText: TDesign Demo }, usingComponents: { t-button: tdesign-miniprogram/button/button } }4. 构建通过但页面异常组件库接入后的高频坑NPM packages not found 解决之后不代表组件就能顺利跑起来。我在实际接入过程中还遇到过几个很典型的后续问题一并列出来避免你走到半路又卡住。4.1 组件路径大小写、少写一层目录TDesign 组件的目录结构通常是组件名/组件名比如tdesign-miniprogram/button/button。很多人在复制文档路径后手写时容易把最后的按钮目录少写一层或者组件名的大小写写错编译时就会提示找不到组件或者找不到对应路径。这类问题有一个统一的排查技巧打开miniprogram_npm/tdesign-miniprogram目录对着真实文件夹结构逐层核对 usingComponents 里的路径一层都不会错。4.2 全局注册后没生效或者开发工具不刷新组件的 json 注册之后开发者工具有时不会立刻刷新组件映射尤其是有缓存的情况下。我遇到过注册写法没问题、代码也对但页面仍然报找不到最后通过 工具栏 - 清缓存 - 清除全部缓存 解决。另外如果你改了 app.json 的 usingComponents建议顺便删掉 miniprogram_npm 目录重新构建一次。工具对全局组件的索引可能还停留在旧构建产物上重新构建可以强制刷新状态。4.3 样式错乱除了 style: v2还有样式隔离如果删掉 style v2 之后样式还是不对需要检查页面或自定义组件的 json 里是否配置了styleIsolation。TDesign 组件内部样式默认是隔离的页面外层样式不会污染到组件内部。反过来如果你在页面 wxss 里想覆盖组件的某些内部样式直接用类名通常不会生效。TDesign 官方推荐的做法是通过 CSS Variables 做主题定制而不是改内部类名。比如在全局样式里覆盖主题色page { --td-brand-color: #0052d9; --td-brand-color-light: #d9e1ff; }这样所有使用 TDesign 颜色变量的组件都会跟着变比一条条改类名可靠得多。4.4 分包场景下组件注册位置如果你的小程序做了分包某一个分包页面要用 TDesign 组件那么 usingComponents 必须写在分包页面自己的 json 里。严格来说TDesign 组件属于主包依赖如果分包里引用了主包组件这个分包就会依赖主包内容对分包体积和加载策略都有影响。实际处理时我的做法是高频基础组件在 app.json 里全局注册低频组件在对应页面 json 里按需注册。TDesign 的按需注入粒度可以精细到组件级配合 lazyCodeLoading 使用效果更好。5. uniapp / HBuilderX 工程里的特殊处理方式5.1 报错的真实工程往往是 dist 目录而不是源码目录很多找到我这个标题的开发者其实不是原生小程序项目而是 uniapp 项目。HBuilderX 运行到微信开发者工具时工具打开的是编译产物目录默认是dist/dev/mp-weixin。每次 HBuilderX 重新运行这个 dist 目录都会被清空重建所以你在微信开发者工具里辛辛苦苦构建出来的 miniprogram_npm下一次 HBuilderX 一运行就又没了。这正是 uniapp 环境下 NPM packages not found 反复出现的根源不是不会配而是编译产物一直在变。第一次构建成功也不能高枕无忧改一行代码再运行问题马上回来。5.2 uniapp 工程接入 TDesign 的可行方案如果确实要在 uniapp 里接入 TDesign 原生版组件流程上是这样在 uniapp 项目根目录安装依赖npm i tdesign-miniprogram -S --production用 HBuilderX 运行到微信开发者工具。到编译产物目录dist/dev/mp-weixin下手动执行一次npm init -y和npm i tdesign-miniprogram -S --production让产物目录下也有完整的依赖。在微信开发者工具里执行 工具 - 构建npm。只要不重新运行 HBuilderX这次构建结果能一直保留到下一次编译前。这个方案的成本非常明显每次 HBuilderX 重新运行之后都要重复第 3、4 步。所以如果你的 uniapp 项目只是图一个组件风格好看我更建议直接使用 uniapp 生态下的 uni-ui 这类纯 Vue 组件库编译链路顺畅得多。TDesign 原生版组件跑在 uniapp 里每次都要处理一遍原生组件映射和 npm 构建维护成本不低。如果是为了统一视觉规范或者某个特定原生组件能力那可以按上面的流程操作算是有得选但要想清楚。5.3 HBuilderX 相关的一个容易混淆的报错热搜词里有个hbuilderx 运行到微信小程序提示不是开发者这个和 NPM packages not found 完全是两码事。前者是微信开发者工具的服务端口没开或者账号没登录排查路径是微信开发者工具 - 设置 - 安全设置 - 打开服务端口再确认当前已登录的微信号是这个小程序项目里的项目成员。两者别混在一起排查否则会在错误的方向上浪费不少时间。6. 组件库接入后值得顺手做的几件事6.1 开启按需注入控制包体积TDesign 全量组件集的体积不小如果 app.json 里全局注册了一堆组件主包会被撑大。可以在 app.json 里加一行{ lazyCodeLoading: requiredComponents }这样基础库会按需注入页面实际使用的组件配合页面级 json 注册主包体积能控制得比较好。基础库版本在 2.11.1 以上都支持新版开发者工具里的项目基本都超过这个版本可以放心使用。6.2 用 CSS Variables 做主题定制前面提过用 CSS 变量覆盖主题色。TDesign 的变量体系不止品牌色还有边框、圆角、字体、阴影等。实际项目里换肤不需要改组件也不需要改页面类名只要在 app.wxss 里覆盖对应变量就全局生效。这种方案对做多主题的小程序特别友好运行期切换只需要动态修改 page 上的变量值。6.3 自定义 tabBar 时优先用 TDesign 的 tabbar 组件TDesign 提供了 t-tabbar 组件配合小程序原生自定义 tabBar 能力使用。接入时需要在项目根目录创建 custom-tab-bar 目录目录里的 index.json 注册 t-tabbarindex.js 里把 tab 配置传进去。这个功能比较实用但有两点要注意自定义 tabBar 的目录名必须叫 custom-tab-bar不能改tab 页面必须是 app.json 里 tabBar.list 中声明的页面否则 tab 切换状态会对不上。6.4 定期清理冗余全局组件TDesign 官方开发者工具能力里有个使用检查可以确认当前项目里哪些 TDesign 组件被实际使用、哪些属于冗余。定期跑一遍把全局注册但没用的组件收敛掉能有效避免主包体积悄悄膨胀。小程序主包体积一旦超过限制影响的不只是发版还会直接影响用户加载体验。最后留个排查顺序备忘我后来再遇到小程序组件库报错基本固定走这个顺序先分清是构建阶段报错还是编译阶段报错再看 miniprogram_npm 目录是否存在然后检查 package.json 位置、packNpmManually 配置、use npm 开关最后才去看 usingComponents 路径和 style v2。整套流程下来大部分 NPM packages not found 都能在十几分钟内解决TDesign 接入也不再是什么难事。希望这份记录能让你少走几个来回。
微信小程序接入TDesign：NPM packages not found 排查全攻略
前阵子在一个原生小程序项目里接入 TDesignnpm install tdesign-miniprogram这一步走得非常顺畅依赖装完我也没多想直接打开微信开发者工具点了一下「工具 - 构建 npm」。结果控制台立刻弹出一行红字NPM packages not found。说实话当时第一反应是装错包了但反复确认了好几遍包名没问题node_modules 下面也确实有 tdesign-miniprogram 目录。后面花了大半天把整个 npm 构建链路从头到尾捋了一遍才算彻底搞明白这个报错背后真正的原因。如果你也在接入 TDesign 时被 NPM packages not found 卡住或者单纯想把小程序里 npm 包的构建机制弄明白这份记录应该能帮你省下不少时间。1. 小程序为什么认不出 node_modules先搞懂构建机制1.1 小程序没有 Web 端的运行时依赖解析在 Web 项目里代码中 import 一个包最终会由打包工具分析依赖树并打进 bundle。小程序不是这个逻辑。小程序运行环境里根本没有 node_modules 的概念你写的 require 或者组件路径tdesign-miniprogram/button/button在运行时都不可能去 node_modules 里找文件它只会去项目里一个固定的目录找——默认是根目录下的 miniprogram_npm。微信开发者工具里的「构建 npm」做的是什么事你可以把它理解成一道搬运工序工具扫描 package.json 里声明的依赖进入 node_modules 找到对应包读取包内 package.json 的 miniprogram 字段指向的源码目录把整份目录原样拷贝到 miniprogram_npm 下同时改写包内部的相对路径让组件之间互相 require 时不会再去依赖 node_modules。也就是说npm 包必须经过构建这一步才可能被小程序运行时识别。这就是许多新手容易懵的地方明明 npm install 成功了package.json 里依赖也写了但页面里使用组件就是报错。原因不是包不存在而是包还没有被搬运到小程序能识别的目录里。1.2 NPM packages not found 到底在说什么NPM packages not found 翻译成大白话就是构建工具开始干活了但它在 package.json、node_modules、miniprogramNpmDistDir 这几个环节里断了链找不到可以构建的 npm 包源。这里要特别注意实际使用中报错分两种场景排查方向完全不一样点击「构建 npm」后立刻报错说明工具没有扫描到任何可用的包。问题大概率出在包本身不是小程序包、package.json 位置不对、npm 开关没打开或者 packNpmManually 配置错误。构建 npm 时没报错但编译页面时提示某个组件 not found。这种情况是 miniprogram_npm 目录里没有对应组件或者说 usingComponents 的路径写错了。很多帖子里把这两种情况混在一起来讲导致排查方向很容易跑偏。提示如果页面编译报错里带的是NPM packages not found这个原文先看一眼资源管理器里有没有生成 miniprogram_npm 目录。目录不存在说明构建步骤本身就没成功目录存在但组件仍然找不到那才是路径或包内部结构的问题。2. NPM packages not found 排查链路六个检查点逐个过这一章把实际排查的过程按顺序整理出来。建议你也按这个顺序来每改一处就先验证再改下一处避免瞎折腾。2.1 检查点一装的是不是 tdesign-miniprogram而不是 tdesign先别急着操作开发者工具打开 package.json看 dependencies 里写的到底是什么。TDesign 有 Web 版、Vue 版、React 版、小程序版小程序版的 npm 包名是tdesign-miniprogram。如果你不小心装成了tdesign那实际引入的是 Web 组件库小程序运行时跑不起来而且这类包大概率没有 miniprogram 字段构建 npm 时工具扫描不到任何可用的包直接就报 NPM packages not found。验证方法很简单打开node_modules/tdesign-miniprogram/package.json看里面有没有一行miniprogram字段。有说明这个包是面向小程序打包过的没有说明包本身就不是小程序组件库。2.2 检查点二项目里有没有 package.json和工具打开的是不是同一个目录构建 npm 的前提是项目根目录有 package.json没有就自己在根目录执行npm init。这里的关键问题是工具打开的根目录到底指哪里。原生小程序项目里app.json 在哪一层project.config.json 的 miniprogramRoot 就指向哪一层package.json 也应该在这一层。如果 miniprogramRoot 是空或者 ./那 package.json 放根目录没毛病。如果工具打开的项目根目录在更外层package.json 被放在了 miniprogram 子目录里那就必须通过 packNpmManually 手动告诉工具 package.json 在哪。这个不懂得配后面就容易一直撞墙。2.3 检查点三packNpmManually 是否配置正确很多项目不是标准的根目录即小程序根目录结构而是这种project-root/ ├─ package.json ├─ project.config.json └─ miniprogram/ ├─ app.js ├─ app.json └─ pages/这种结构下project.config.json 里 miniprogramRoot 指向 ./miniprogram而 package.json 在根目录。如果不做任何配置工具会跑到 miniprogram 目录里找 package.json找不到自然就报 NPM packages not found。解决办法是在 project.config.json 的 setting 里配置 packNpmManually 和 packNpmRelationList{ miniprogramRoot: ./miniprogram/, setting: { packNpmManually: true, packNpmRelationList: [ { packageJsonPath: ./package.json, miniprogramNpmDistDir: ./miniprogram/ } ] } }packageJsonPath告诉构建工具去哪个位置找 package.json。miniprogramNpmDistDir构建出来的 miniprogram_npm 放到哪个目录必须和你实际的小程序根目录一致。如果项目没有子目录app.json 就在根目录那 miniprogramNpmDistDir 直接写 ./ 就行。我最早就是在这里栽的项目结构带了一层 miniprogram 子目录packNpmRelationList 没配工具每次都在子目录里找 package.json结果折腾了很长时间才发现是路径配置的问题。2.4 检查点四本地设置里的使用npm模块开关在项目打开的开发者工具里点「详情 - 本地设置」找到「使用npm模块」开关确认它是勾选状态。这个开关在老版本里是 npm 构建的必要前置条件没有开启就点构建 npm即使其他配置全对也会提示找不到包。新版本工具里它默认是开的但有些从同事那里 clone 来的项目、或者本地配置和项目配置分离的场景下可能被关掉了。勾选之后建议把项目整个关掉重新打开一次再点构建 npm。这一步虽然是基础操作但很多人就是在这里疏忽了。2.5 检查点五node_modules 是不是 pnpm 装的这个坑容易被忽略。微信开发者工具对 pnpm 创建的符号链接结构支持有限。pnpm 安装依赖后node_modules 里是一堆软链工具扫描依赖时经常解析不到真实的包目录结果就是包明明装好了构建 npm 却一直说找不到包报 NPM packages not found。我在一个 monorepo 风格的项目里遇到过一次最后换回 npm install 重装依赖问题立刻消失。如果你是用 pnpm 在管理工程建议在小程序工程目录里单独用 npm 初始化一份依赖或者至少在小程序这一层用 npm 安装组件库不要直接复用 pnpm 的 node_modules。2.6 检查点六构建路径和工具版本剩下的两类问题比较玄学。一类是项目路径带中文或者空格老版本的构建工具在这种路径下解析包路径会出错从而报 NPM packages not found。现在虽然修复了不少但如果你怎么都排查不出来可以试试把项目拷贝到全英文路径下再构建一次花不了几分钟。另一类是微信开发者工具版本太旧。npm 构建能力一直在迭代不少历史 bug 都是在新版修复的。遇到怎么都说不通的问题先把工具升级到最新稳定版然后工具栏 - 清缓存 - 清除全部缓存关掉项目重新打开再走一遍构建流程。3. TDesign 最小可运行配置从安装到页面渲染3.1 正确的安装命令与依赖声明确认构建工具没问题之后剩下的就是 TDesign 本身的接入。TDesign 微信小程序版的最小接入步骤如下先在小程序根目录生成 package.json 并安装依赖npm init -y npm i tdesign-miniprogram -S --production这里有两个容易被忽视的点。第一必须加--production。加了这个参数npm 只会安装 dependencies 里的正式依赖devDependencies 里的内容不会被打包进 miniprogram_npm可有效控制小程序包体积。第二安装完成后看一下 package.json确保 tdesign-miniprogram 出现在 dependencies 下面而不是 devDependencies。如果出现在 devDependencies 里构建 npm 时工具默认不会处理它组件照样引入不了。3.2 project.config.json 推荐配置如果你和我一样用的是单目录原生小程序结构app.json 和 package.json 同层可以直接采用下面这套配置能省掉后面很多判断{ miniprogramRoot: ./, setting: { es6: true, postcss: true, minified: true, packNpmManually: true, packNpmRelationList: [ { packageJsonPath: ./package.json, miniprogramNpmDistDir: ./ } ] } }配置保存后重新打开项目再点「工具 - 构建npm」。正常情况下控制台会输出构建成功项目里多出miniprogram_npm/tdesign-miniprogram目录。提示如果构建成功但 miniprogram_npm 里只有一个空的 tdesign-miniprogram 目录说明工具读到了包但包内 miniprogram 字段指向的源码目录不对。打开 node_modules/tdesign-miniprogram/package.json 检查一下 miniprogram 字段的路径确认它实际指向的目录下有没有组件文件。3.3 注册组件的路径到底怎么写TDesign 官方文档给出的使用方式是在 app.json 里全局注册比如{ usingComponents: { t-button: tdesign-miniprogram/button/button, t-icon: tdesign-miniprogram/icon/icon } }注意这个路径写法是有讲究的。它省略了miniprogram_npm前缀也省略了node_modules前缀直接以包名tdesign-miniprogram开头。工具在编译时会自动把这种写法映射到miniprogram_npm/tdesign-miniprogram/button/button。如果你写成miniprogram_npm/tdesign-miniprogram/button/button有一部分项目也能生效但官方并不推荐因为一旦重新构建或者换了构建目录配置这种硬编码路径很容易断。实际操作时我建议只在用到组件的页面 json 里注册或者全局只注册高频基础组件。TDesign 全家桶有几十个组件全量全局注册会让主包体积膨胀很快。注册完之后在 wxml 里直接使用t-button typeprimary sizelarge登录/t-button3.4 app.json 里要删除 style: v2这一步非常容易漏。微信小程序默认工程里 app.json 通常有style: v2配置v2 样式会影响部分 TDesign 组件的表现比如按钮内边距不正确、导航栏偏移、单元格高度异常。TDesign 官方文档明确建议把 app.json 里的style: v2删掉。删除后需要清缓存重新编译一次很多组件明明引入成功但长得不对劲的问题都是这个细节引起的。删除之后 app.json 大概长这样{ pages: [pages/index/index], window: { navigationBarTitleText: TDesign Demo }, usingComponents: { t-button: tdesign-miniprogram/button/button } }4. 构建通过但页面异常组件库接入后的高频坑NPM packages not found 解决之后不代表组件就能顺利跑起来。我在实际接入过程中还遇到过几个很典型的后续问题一并列出来避免你走到半路又卡住。4.1 组件路径大小写、少写一层目录TDesign 组件的目录结构通常是组件名/组件名比如tdesign-miniprogram/button/button。很多人在复制文档路径后手写时容易把最后的按钮目录少写一层或者组件名的大小写写错编译时就会提示找不到组件或者找不到对应路径。这类问题有一个统一的排查技巧打开miniprogram_npm/tdesign-miniprogram目录对着真实文件夹结构逐层核对 usingComponents 里的路径一层都不会错。4.2 全局注册后没生效或者开发工具不刷新组件的 json 注册之后开发者工具有时不会立刻刷新组件映射尤其是有缓存的情况下。我遇到过注册写法没问题、代码也对但页面仍然报找不到最后通过 工具栏 - 清缓存 - 清除全部缓存 解决。另外如果你改了 app.json 的 usingComponents建议顺便删掉 miniprogram_npm 目录重新构建一次。工具对全局组件的索引可能还停留在旧构建产物上重新构建可以强制刷新状态。4.3 样式错乱除了 style: v2还有样式隔离如果删掉 style v2 之后样式还是不对需要检查页面或自定义组件的 json 里是否配置了styleIsolation。TDesign 组件内部样式默认是隔离的页面外层样式不会污染到组件内部。反过来如果你在页面 wxss 里想覆盖组件的某些内部样式直接用类名通常不会生效。TDesign 官方推荐的做法是通过 CSS Variables 做主题定制而不是改内部类名。比如在全局样式里覆盖主题色page { --td-brand-color: #0052d9; --td-brand-color-light: #d9e1ff; }这样所有使用 TDesign 颜色变量的组件都会跟着变比一条条改类名可靠得多。4.4 分包场景下组件注册位置如果你的小程序做了分包某一个分包页面要用 TDesign 组件那么 usingComponents 必须写在分包页面自己的 json 里。严格来说TDesign 组件属于主包依赖如果分包里引用了主包组件这个分包就会依赖主包内容对分包体积和加载策略都有影响。实际处理时我的做法是高频基础组件在 app.json 里全局注册低频组件在对应页面 json 里按需注册。TDesign 的按需注入粒度可以精细到组件级配合 lazyCodeLoading 使用效果更好。5. uniapp / HBuilderX 工程里的特殊处理方式5.1 报错的真实工程往往是 dist 目录而不是源码目录很多找到我这个标题的开发者其实不是原生小程序项目而是 uniapp 项目。HBuilderX 运行到微信开发者工具时工具打开的是编译产物目录默认是dist/dev/mp-weixin。每次 HBuilderX 重新运行这个 dist 目录都会被清空重建所以你在微信开发者工具里辛辛苦苦构建出来的 miniprogram_npm下一次 HBuilderX 一运行就又没了。这正是 uniapp 环境下 NPM packages not found 反复出现的根源不是不会配而是编译产物一直在变。第一次构建成功也不能高枕无忧改一行代码再运行问题马上回来。5.2 uniapp 工程接入 TDesign 的可行方案如果确实要在 uniapp 里接入 TDesign 原生版组件流程上是这样在 uniapp 项目根目录安装依赖npm i tdesign-miniprogram -S --production用 HBuilderX 运行到微信开发者工具。到编译产物目录dist/dev/mp-weixin下手动执行一次npm init -y和npm i tdesign-miniprogram -S --production让产物目录下也有完整的依赖。在微信开发者工具里执行 工具 - 构建npm。只要不重新运行 HBuilderX这次构建结果能一直保留到下一次编译前。这个方案的成本非常明显每次 HBuilderX 重新运行之后都要重复第 3、4 步。所以如果你的 uniapp 项目只是图一个组件风格好看我更建议直接使用 uniapp 生态下的 uni-ui 这类纯 Vue 组件库编译链路顺畅得多。TDesign 原生版组件跑在 uniapp 里每次都要处理一遍原生组件映射和 npm 构建维护成本不低。如果是为了统一视觉规范或者某个特定原生组件能力那可以按上面的流程操作算是有得选但要想清楚。5.3 HBuilderX 相关的一个容易混淆的报错热搜词里有个hbuilderx 运行到微信小程序提示不是开发者这个和 NPM packages not found 完全是两码事。前者是微信开发者工具的服务端口没开或者账号没登录排查路径是微信开发者工具 - 设置 - 安全设置 - 打开服务端口再确认当前已登录的微信号是这个小程序项目里的项目成员。两者别混在一起排查否则会在错误的方向上浪费不少时间。6. 组件库接入后值得顺手做的几件事6.1 开启按需注入控制包体积TDesign 全量组件集的体积不小如果 app.json 里全局注册了一堆组件主包会被撑大。可以在 app.json 里加一行{ lazyCodeLoading: requiredComponents }这样基础库会按需注入页面实际使用的组件配合页面级 json 注册主包体积能控制得比较好。基础库版本在 2.11.1 以上都支持新版开发者工具里的项目基本都超过这个版本可以放心使用。6.2 用 CSS Variables 做主题定制前面提过用 CSS 变量覆盖主题色。TDesign 的变量体系不止品牌色还有边框、圆角、字体、阴影等。实际项目里换肤不需要改组件也不需要改页面类名只要在 app.wxss 里覆盖对应变量就全局生效。这种方案对做多主题的小程序特别友好运行期切换只需要动态修改 page 上的变量值。6.3 自定义 tabBar 时优先用 TDesign 的 tabbar 组件TDesign 提供了 t-tabbar 组件配合小程序原生自定义 tabBar 能力使用。接入时需要在项目根目录创建 custom-tab-bar 目录目录里的 index.json 注册 t-tabbarindex.js 里把 tab 配置传进去。这个功能比较实用但有两点要注意自定义 tabBar 的目录名必须叫 custom-tab-bar不能改tab 页面必须是 app.json 里 tabBar.list 中声明的页面否则 tab 切换状态会对不上。6.4 定期清理冗余全局组件TDesign 官方开发者工具能力里有个使用检查可以确认当前项目里哪些 TDesign 组件被实际使用、哪些属于冗余。定期跑一遍把全局注册但没用的组件收敛掉能有效避免主包体积悄悄膨胀。小程序主包体积一旦超过限制影响的不只是发版还会直接影响用户加载体验。最后留个排查顺序备忘我后来再遇到小程序组件库报错基本固定走这个顺序先分清是构建阶段报错还是编译阶段报错再看 miniprogram_npm 目录是否存在然后检查 package.json 位置、packNpmManually 配置、use npm 开关最后才去看 usingComponents 路径和 style v2。整套流程下来大部分 NPM packages not found 都能在十几分钟内解决TDesign 接入也不再是什么难事。希望这份记录能让你少走几个来回。
