微信小程序npm扩展能力探究

定栓2024-09-05 8:55

文章目录

小程序支持使用 npm 安装第三方包。

创建 package.json

可以在小程序终端执行 npm init，逐个输入项目信息，或执行快捷命令 npm init -y，自动填充信息，两种方式最终都会生成 package.json 文件。

使用 npm 包

  1. 在 package.json 所在的目录执行命令安装 npm 包：npm i，在同级形成 node_modules 目录。
  2. 点击开发者工具中的菜单栏：工具 --> 构建 npm
  3. 构建完成后会在同级创建 miniprogram_npm 目录，构建后的包均在该目录下。

看到这里你大概知道了，小程序中不会直接引用 node_modules 中的包，而是需要进行构建，构建后的包才是小程序可用的包。

一般情况下，package.json 放在项目根目录中，因此原始 node_modules 目录与构建后的 miniprogram_npm 目录都会在根目录中。

使用构建后的包自定义组件

json 复制代码 
{
  "usingComponents": {
    "myPackage": "packageName",
    "package-other": "packageName/other"
  }
}

这里我们以使用 vant（小程序版） 为例。首先进行下载：

js 复制代码 
# 通过 npm 安装
npm i @vant/weapp -S --production

# 通过 yarn 安装
yarn add @vant/weapp --production

执行构建，出现 miniprogram_npm 目录，那我们开始引入 Button 按钮组件，在全局文件 app.json 或 页面 page.json 中引入组件。

json 复制代码 
"usingComponents": {
  "van-button": "@vant/weapp/button/index"
}

在页面 wxml 文件中进行使用：

html 复制代码 
<van-button type="default">默认按钮</van-button>
<van-button type="primary">主要按钮</van-button>
<van-button type="info">信息按钮</van-button>
<van-button type="warning">警告按钮</van-button>
<van-button type="danger">危险按钮</van-button>

接着看到模拟器显示了我们引入的按钮。好了，到这里是不是很兴奋，我们终于可以继续使用我们在其他端用的顺手的组件库了。

小程序 js 中引入构建后的包

js 复制代码 
const myPackage = require('packageName')
const packageOther = require('packageName/other')

以下为官方提供的 js 模块 sm-crypto为例，首先进行下载：

cmd 复制代码 
npm i -S miniprogram-sm-crypto

执行构建，然后在 js 文件中进行引入：

js 复制代码 
const sm2 = require('miniprogram-sm-crypto').sm2
console.log(sm2)

可在调试器 console 上看到打印的信息。到这我们可以使用 js 编写的函数库了。

npm 构建方式

接下来我们该了解下 node_modules 包构建后形成 miniprogram_npm 包的方式及过程。

构建是依据 package.json 的 dependencies 字段，所以声明在 devDependencies 里的包可以在开发过程中被安装使用而不会参与到构建中。如果是开发者工具 v1.02.1811150 之前的版本，则建议使用 --production 选项，可以减少一些业务无关的 npm 安装包，从而减少整个小程序包的大小。

目前提供了两种构建 npm 的方式。

默认方式

默认情况，项目根目录中 project.config.json 文件中字段 miniprogramRoot 指定小程序源码的目录(需为相对路径)，当该字段不存在时，miniprogramRoot 就是 project.config.json 所在的目录。

在每个 package.json 执行 npm i 之后，其构建 npm 的结果是，为每一个 package.json 对应的 node_modules 构建一份 miniprogram_npm，并放置在同级目录中。

构建前

txt 复制代码 
├── miniprogram
│   ├── app.js
│   ├── app.json
│   ├── app.wxss
│   ├── index
│   │   ├── 略
│   ├── node_modules // 可被默认方式构建 npm，因为它在 miniprogramRoot 内
│   ├── package.json
│   └── sub_package
│       ├── node_modules // 可被默认方式构建 npm，因为它在 miniprogramRoot 内
│       ├── package.json
│       └── sub_package_page
├── node_modules // 不被默认方式构建 npm，因为它不在 miniprogramRoot 指定的目录内
├── package.json
└── project.config.json // 其中存在配置 "miniprogramRoot": "./miniprogram"

构建后

txt 复制代码 
├── miniprogram
│   ├── app.js
│   ├── app.json
│   ├── app.wxss
│   ├── index
│   │   ├── 略
│   ├── miniprogram_npm
│   ├── node_modules // 可被默认方式构建 npm，因为它在 miniprogramRoot 内 --> 同级的 miniprogram_npm 是这份 node_modules 的构建结果
│   ├── package.json
│   └── sub_package
│       ├── miniprogram_npm 
│       ├── node_modules // 可被默认方式构建 npm，因为它在 miniprogramRoot 内 --> 同级的 miniprogram_npm 是这份 node_modules 的构建结果
│       ├── package.json
│       └── sub_package_page
├── node_modules // 不被默认方式构建 npm，因为它不在 miniprogramRoot 指定的目录内 --> 它并没有对应的 miniprogram_npm 生成
├── package.json
└── project.config.json // 其中存在配置 "miniprogramRoot": "./miniprogram"

可以参考例子 demo，实际构建下，会让你理解的更为深刻。

自定义 node_modules 和 miniprogram_npm 位置的构建方式

此处要求参与构建 npm 的 package.json 文件需要在 project.config.json 定义的 miniprogramRoot 目录中。

与默认方式不一样，此种方式需要开发者在 project.config.json 中指定 node_modules 的位置和构建产物 miniprogram_npm 的位置。

用法

  • 配置 project.config.json 的 setting.packNpmManually 为 true，开启自定义 node_modules 和 miniprogram_npm 位置的构建方式
  • 配置 project.config.json 的 setting.packNpmRelationList 项，指定 packageJsonPath 和 miniprogramNpmDistDir 的位置

其中 packNpmRelationList 用 TS 表示数据结构为：

js 复制代码 
packNpmRelationList: Array<{
  "packageJsonPath": string,
  "miniprogramNpmDistDir": string
}>
  • packageJsonPath 表示 node_modules 所对应的 package.json
  • miniprogramNpmDistDir 表示 node_modules 的构建结果 miniprogram_npm 位置

构建前

txt 复制代码 
├── miniprogram
│   ├── app.js
│   ├── app.json
│   ├── app.wxss
│   ├── index
│   ├── sitemap.json
│   └── sub_package
│       └── sub_package_page
├── project.config.json
├── src_node_modules_1
│   ├── node_modules
│   └── package.json
└── src_node_modules_2
    ├── node_modules
    └── package.json

其中 project.config.json 存在配置

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"
    }
  ]
}

构建后

txt 复制代码 
├── miniprogram
│   ├── app.js
│   ├── app.json
│   ├── app.wxss
│   ├── index
│   ├── miniprogram_npm // 由 src_node_modules_1/node_modules 构建得到
│   ├── sitemap.json
│   └── sub_package
│       ├── miniprogram_npm // 由 src_node_modules_2/node_modules 构建得到
│       └── sub_package_page
├── project.config.json
├── src_node_modules_1
│   ├── node_modules
│   └── package.json
└── src_node_modules_2
    ├── node_modules
    └── package.json

可以参考例子 demo，实际构建下，会让你理解的更为深刻。

发布小程序 npm 包

发布新包的约束

这里要发布的 npm 包是特指专为小程序定制的 npm 包（下称小程序 npm 包）。因为小程序自定义组件的特殊性，原有的 npm 包机制无法满足我们的需求，所以这里需要对小程序 npm 包做一些约束：

  1. 小程序 npm 包要求根目录下必须有构建文件生成目录（默认为 dist 目录），此目录可以通过在 package.json 文件中新增一个 miniprogram 字段来指定，比如：
json 复制代码 
{
  "name": "miniprogram-custom-component",
  "version": "1.0.0",
  "description": "",
  "miniprogram": "dist",
  "devDependencies": {},
  "dependencies": {}
}

该 miniprogram 字段在编辑器进行 构建 npm 时，将该字段值的目录文件复制到 miniprogram_npm 目录下的同名包中。

  1. 小程序 npm 包里只有构建文件生成目录会被算入小程序包的占用空间，上传小程序代码时也只会上传该目录的代码。如果小程序 npm 包有一些测试、构建相关的代码请放到构建文件生成目录外。另外也可以使用 .npmignore 文件来避免将一些非业务代码文件发布到 npm 中。

  2. 测试、构建相关的依赖请放入 devDependencies 字段中避免被一起打包到小程序包中。

改造已有包的约束

如果是已经发布过的一些 npm 包，因为一些原因无法改造成小程序 npm 包的结构的话，也可以通过微调后被使用，但是请确保遵循以下几点：

  1. 只支持纯 js 包，不支持自定义组件。
  2. 必须有入口文件，即需要保证 package.json 中的 main 字段是指向一个正确的入口，如果 package.json 中没有 main 字段，则以 npm 包根目录下的 index.js 作为入口文件。
  3. 测试、构建相关的依赖请放入 devDependencies 字段中避免被一起打包到小程序包中，这一点和小程序 npm 包的要求相同。
  4. 不支持依赖 c++ addon，不支持依赖 nodejs 的内置库：
js 复制代码 
const addon = require('./addon.node'); // 不支持！
const http = require('http'); // 不支持！
  1. 小程序环境比较特殊，一些全局变量（如 window 对象，document 对象）和构造器（如 Function 构造器）是无法使用的。
  2. 对于一些纯 js 实现的 nodejs 内置库（如 path 模块），可以通过额外安装其他开发者实现的 npm 包来支持。
  3. 此处使用 npm 包时如果只引入包名，则默认寻找包名下的 index.js 文件或者 index 组件。
  4. 使用 require 依赖的时候下列几种方式也是不允许的：
js 复制代码 
// 不允许将 require 赋值给其他变量后再使用，以下代码不会去解析出具体依赖
let r;
r = require;
r('testa');

let r2 = require;
r2('testa');

// 不允许 require 一个变量，以下代码依赖运行时，无法解析出具体依赖
let m = 'testa';
require(m);

进行发布

发布 npm 包流程可以参考这篇文章公共资源包发布流程详解

原理介绍

为了帮助大家更好的理解发布 npm 包中提到的各种要求，这里简单介绍一下原理：

  1. 首先 node_modules 目录中的代码不会参与小程序代码的编译、打包和上传，小程序仅能使用 npm 构建后形成的 miniprogram_npm 目录中的包。
  2. 构建打包分为两种：一种是：小程序 npm 包会直接拷贝构建后生成的目录文件（如在 package.json 文件中 miniprogram 指定为 dist）到 miniprogram_npm 中；另一种是：npm 包则会从入口 js 文件开始走一遍依赖分析和打包过程（类似 webpack）。
  3. 寻找小程序可用的 npm 包的过程和 常规 npm 的实现类似，从依赖 npm 包的文件所在目录开始逐层往外找，直到找到可用的 npm 包或是小程序根目录为止。

下面简单介绍下构建打包前后的目录情况。

构建之前的结构：

txt 复制代码 
|--node_modules
|    |--testComp // 小程序 npm 包
|    |    |--package.json
|    |    |--src
|    |    |--miniprogram_dist
|    |         |-index.js
|    |         |-index.json
|    |         |-index.wxss
|    |         |-index.wxml
|    |--testa // 其他 npm 包
|         |--package.json
|         |--lib
|         |    |--entry.js
|         |--node_modules
|              |--testb
|                   |--package.json
|                   |--main.js
|--pages
|--app.js
|--app.wxss
|--app.json
|--project.config.js

构建之后的结构：

txt 复制代码 
|--node_modules
|--miniprogram_npm
|    |--testComp // 小程序 npm 包
|    |    |-index.js
|    |    |-index.json
|    |    |-index.wxss
|    |    |-index.wxml
|    |--testa // 其他 npm 包
|         |--index.js // 打包后的文件
|         |--miniprogram_npm
|              |--testb
|                   |--index.js // 打包后的文件
|                   |--index.js.map
|--pages
|--app.js
|--app.wxss
|--app.json
|--project.config.js

tips：打包生成的代码在同级目录下会生成 source map 文件，方便进行逆向调试。

开发第三方自定义组件

请查阅开发第三方自定义组件文档。

miniprogram_npm 组件寻址顺序

页面配置文件（如：pages/index/index.json）中使用 usingComponents

json 复制代码 
{
  "usingComponents": {
    "a": "a"
  }
}

其寻址顺序为

json 复制代码 
[
  // 先寻址相对路径
  "pages/index/a",
  "pages/index/a/index",
  // 再尝试寻址 miniprogram_npm 下的组件
  "pages/index/miniprogram_npm/a",
  "pages/index/miniprogram_npm/a/index",
  // 再尝试其父层级中的 miniprogram_npm 目录
  "pages/miniprogram_npm/a",
  "pages/miniprogram_npm/a/index",
  "miniprogram_npm/a",
  "miniprogram_npm/a/index"
]

tips：建议对于组件是 a/index 和 a/a 的这种情况，或者同时存在 a 和 a/index 的情况，usingComponents 需要直接显示的写明 "a/index" 和 "a/a"，而不是只写 "a"。

相关推荐
编程千纸鹤4 小时前
高校宿舍信息管理系统小程序
小程序·宿舍管理小程序
说私域5 小时前
基于开源 AI 智能名片 S2B2C 商城小程序的视频号交易小程序优化研究
人工智能·小程序·零售
fg_4119 小时前
无网络安装ionic和运行
前端·npm
丁总学Java16 小时前
微信小程序，点击bindtap事件后，没有跳转到详情页，有可能是app.json中没有正确配置页面路径
微信小程序·小程序·json
说私域17 小时前
基于开源 AI 智能名片、S2B2C 商城小程序的用户获取成本优化分析
人工智能·小程序
mosen86818 小时前
Uniapp去除顶部导航栏-小程序、H5、APP适用
vue.js·微信小程序·小程序·uni-app·uniapp
qq229511650218 小时前
微信小程序的汽车维修预约管理系统
微信小程序·小程序·汽车
尚梦1 天前
uni-app 封装刘海状态栏（适用小程序， h5, 头条小程序）
前端·小程序·uni-app
小飞哥liac1 天前
微信小程序的组件
微信小程序
GDAL1 天前
npm入门教程1：npm简介
前端·npm·node.js
热门推荐
01如何才能让手机厂商主动拥抱华为，接入鸿蒙系统？02【HarmonyOS】HUAWEI DevEco Studio 下载地址汇总03组基轨迹建模 GBTM的介绍与实现（Stata 或 R）04【TC3xx芯片】TC3xx芯片电源管理系统PMS详解05基于YOLOv10深度学习的CT扫描图像肾结石智能检测系统【python源码+Pyqt5界面+数据集+训练代码】深度学习实战、目标检测06【经验分享】Ubuntu22.04安装微信(linux官方版)07Macbook pro M1 安装Ubuntu教程08RAG 实践- Ollama+RagFlow 部署本地知识库09Windows10安装PCL1.14.0及点云配准10文件或文件夹名称中有空格如何批量去除