微信小程序集成 TDesign 完整记录：解决 NPM packages not found

微信小程序集成 TDesign 完整记录：解决 `NPM packages not found`

最近在微信小程序项目里接入 TDesign，组件本身很好用，但安装过程没有想象中那么顺。

主要问题出现在 微信开发者工具构建 npm 这一步。

TDesign 官方文档对这个问题只有一句简单提示，让你去微信小程序官方文档配置 packNpmManually 和 packNpmRelationList，但微信官方给出的配置又比较抽象，我一开始完全没理解这些路径应该怎么填。

折腾了很久才配置成功，所以把整个接入过程记录下来。

TDesign 官方文档：

tdesign.tencent.com/miniprogram...

安装 TDesign

微信小程序已经支持通过 npm 安装第三方依赖，直接执行：

css 复制代码

npm i tdesign-miniprogram -S --production

安装完成之后，项目根目录会出现：

csharp 复制代码

node_modules/
package-lock.json

但这时候还不能直接在小程序中使用。

还需要打开 微信开发者工具，执行：

rust 复制代码

工具 -> 构建 npm

TDesign 官方文档对此的说明是：

安装完之后，需要在微信开发者工具中对 npm 进行构建：工具 - 构建 npm。

构建时若出现 NPM packages not found 字样，请到 project.config.json 文件补充 packNpmManually 和 packNpmRelationList 配置项。

我这里执行构建之后，刚好就出现了：

复制代码

NPM packages not found

于是开始按照文档继续排查。

`NPM packages not found`

TDesign 文档给出的解决方向是查看微信小程序官方的 NPM 支持文档：

developers.weixin.qq.com/miniprogram...

里面给出了类似下面的配置：

json 复制代码

{
  "setting": {
    "packNpmManually": true,
    "packNpmRelationList": [
      {
        "packageJsonPath": "./src_node_modules_1/package.json",
        "miniprogramNpmDistDir": "./miniprogram/"
      },
      {
        "packageJsonPath": "./src_node_modules_2/package.json",
        "miniprogramNpmDistDir": "./miniprogram/sub_package"
      }
    ]
  }
}

第一次看到这个配置，我完全没理解。

尤其是：

json 复制代码

"packageJsonPath": "./src_node_modules_1/package.json"

我的项目里根本没有：

复制代码

src_node_modules_1

另外：

json 复制代码

"miniprogramNpmDistDir": "./miniprogram/"

到底应该填写项目根目录、npm 目录，还是小程序源码目录，也不是特别直观。

后来才搞清楚，微信官方这里给的是一个 多 npm 依赖目录、多小程序目录的示例。

src_node_modules_1 并不是什么微信小程序规定的固定目录，只是官方为了演示而使用的示例路径。

对于普通项目，需要根据自己的目录结构修改。

我的项目结构大概是：

lua 复制代码

project/
├── miniprogram/
├── node_modules/
├── package.json
├── package-lock.json
└── project.config.json

也就是：

go 复制代码

package.json

在项目根目录，而真正的小程序源码在：

复制代码

miniprogram/

所以最后把 project.config.json 修改成：

json 复制代码

{
  "setting": {
    "packNpmManually": true,
    "packNpmRelationList": [
      {
        "packageJsonPath": "./package.json",
        "miniprogramNpmDistDir": "./miniprogram/"
      }
    ]
  }
}

再次执行：

rust 复制代码

工具 -> 构建 npm

终于构建成功。

这里其实可以简单理解成：

json 复制代码

"packageJsonPath": "./package.json"

表示：

go 复制代码

npm 依赖从哪个 package.json 查找

而：

json 复制代码

"miniprogramNpmDistDir": "./miniprogram/"

表示：

复制代码

这个 npm 依赖对应哪个小程序目录

因此如果你的项目也是常见的：

go 复制代码

project/
├── package.json
├── node_modules/
└── miniprogram/

那么基本直接使用下面的配置即可：

json 复制代码

{
  "setting": {
    "packNpmManually": true,
    "packNpmRelationList": [
      {
        "packageJsonPath": "./package.json",
        "miniprogramNpmDistDir": "./miniprogram/"
      }
    ]
  }
}

构建成功之后，在 miniprogram 下可以看到生成的：

复制代码

miniprogram_npm/

其中就包含刚才安装的：

复制代码

tdesign-miniprogram

开启 ES5 编译

按照 TDesign 官方文档的要求，npm 构建成功后，还需要在微信开发者工具中勾选：

复制代码

将 JS 编译成 ES5

这个选项可以在开发者工具的项目设置中找到。

修改 app.json

接下来检查：

bash 复制代码

miniprogram/app.json

如果里面存在：

json 复制代码

{
  "style": "v2"
}

需要将：

json 复制代码

"style": "v2"

删除。

也就是不要使用：

json 复制代码

{
  "style": "v2"
}

TDesign 官方给出的原因是，微信小程序的这个配置会启用新版组件样式，可能导致 TDesign 的组件样式发生错乱。

微信官方对 style 的说明：

developers.weixin.qq.com/miniprogram...

因此如果原来的 app.json 是：

json 复制代码

{
  "pages": [
    "pages/index/index"
  ],
  "style": "v2"
}

修改为：

json 复制代码

{
  "pages": [
    "pages/index/index"
  ]
}

即可。

修改 tsconfig.json

如果项目使用 TypeScript，还需要配置 tsconfig.json。

增加：

json 复制代码

{
  "compilerOptions": {
    "paths": {
      "tdesign-miniprogram/*": [
        "./miniprogram/miniprogram_npm/tdesign-miniprogram/*"
      ]
    }
  }
}

关键配置是：

json 复制代码

"tdesign-miniprogram/*": [
  "./miniprogram/miniprogram_npm/tdesign-miniprogram/*"
]

因为微信开发者工具执行 npm 构建之后，真正供小程序使用的 TDesign 代码位于：

bash 复制代码

miniprogram/miniprogram_npm/tdesign-miniprogram/

通过 paths 将：

复制代码

tdesign-miniprogram/*

映射到构建后的实际目录，TypeScript 才能正确识别相关引用。

使用 TDesign 组件

完成上面的配置之后，就可以正常使用 TDesign 组件了。

以 Button 为例。

在页面对应的 JSON 文件中增加：

css 复制代码

{
  "usingComponents": {
    "t-button": "tdesign-miniprogram/button/button"
  }
}

然后直接在 WXML 中使用：

ini 复制代码

<t-button theme="primary">按钮</t-button>

如果页面能够正常显示 TDesign 按钮，就说明整个接入过程已经完成。

完整流程实际上就是：

markdown 复制代码

安装 tdesign-miniprogram
        ↓
微信开发者工具构建 npm
        ↓
解决 NPM packages not found
        ↓
生成 miniprogram_npm
        ↓
开启「将 JS 编译成 ES5」
        ↓
删除 app.json 中的 style: v2
        ↓
配置 tsconfig.json paths
        ↓
usingComponents 引入组件
        ↓
WXML 中使用

其中真正让我卡了比较久的，就是微信官方文档中的：

json 复制代码

"packageJsonPath": "./src_node_modules_1/package.json"

这个例子。

一开始还以为 src_node_modules_1 是修改 tdesign-miniprogram 的 npm 包的路径名。

最后才发现它单纯只是官方示例中的目录名。

对于普通的根目录 npm 项目，直接：

json 复制代码

"packageJsonPath": "./package.json"

就可以了。

故记录。