文章目录
小程序支持使用 npm 安装第三方包。
创建 package.json
可以在小程序终端执行 npm init，逐个输入项目信息，或执行快捷命令 npm init -y，自动填充信息，两种方式最终都会生成 package.json 文件。
使用 npm 包
- 在 package.json 所在的目录执行命令安装 npm 包：
npm i，在同级形成 node_modules 目录。 - 点击开发者工具中的菜单栏：工具 --> 构建 npm
- 构建完成后会在同级创建 miniprogram_npm 目录，构建后的包均在该目录下。
看到这里你大概知道了，小程序中不会直接引用 node_modules 中的包，而是需要进行构建，构建后的包才是小程序可用的包。
一般情况下，package.json 放在项目根目录中，因此原始 node_modules 目录与构建后的 miniprogram_npm 目录都会在根目录中。
使用构建后的包自定义组件
{
"usingComponents": {
"myPackage": "packageName",
"package-other": "packageName/other"
}
}
这里我们以使用 vant（小程序版） 为例。首先进行下载：
# 通过 npm 安装
npm i @vant/weapp -S --production
# 通过 yarn 安装
yarn add @vant/weapp --production
执行构建，出现 miniprogram_npm 目录，那我们开始引入 Button 按钮组件，在全局文件 app.json 或 页面 page.json 中引入组件。
"usingComponents": {
"van-button": "@vant/weapp/button/index"
}
在页面 wxml 文件中进行使用：
<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 中引入构建后的包
const myPackage = require('packageName')
const packageOther = require('packageName/other')
以下为官方提供的 js 模块 sm-crypto为例，首先进行下载：
npm i -S miniprogram-sm-crypto
执行构建，然后在 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，并放置在同级目录中。
构建前
├── 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"
构建后
├── 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 表示数据结构为：
packNpmRelationList: Array<{
"packageJsonPath": string,
"miniprogramNpmDistDir": string
}>
- packageJsonPath 表示 node_modules 所对应的 package.json
- miniprogramNpmDistDir 表示 node_modules 的构建结果 miniprogram_npm 位置
构建前
├── 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 存在配置
"setting": {
"packNpmManually": true,
"packNpmRelationList": [
{
"packageJsonPath": "./src_node_modules_1/package.json",
"miniprogramNpmDistDir": "./miniprogram/"
},
{
"packageJsonPath": "./src_node_modules_2/package.json",
"miniprogramNpmDistDir": "./miniprogram/sub_package"
}
]
}
构建后
├── 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 包做一些约束：
- 小程序 npm 包要求根目录下必须有构建文件生成目录（默认为 dist 目录），此目录可以通过在 package.json 文件中新增一个 miniprogram 字段来指定，比如：
{
"name": "miniprogram-custom-component",
"version": "1.0.0",
"description": "",
"miniprogram": "dist",
"devDependencies": {},
"dependencies": {}
}
该 miniprogram 字段在编辑器进行 构建 npm 时，将该字段值的目录文件复制到 miniprogram_npm 目录下的同名包中。
-
小程序 npm 包里只有构建文件生成目录会被算入小程序包的占用空间，上传小程序代码时也只会上传该目录的代码。如果小程序 npm 包有一些测试、构建相关的代码请放到构建文件生成目录外。另外也可以使用
.npmignore文件来避免将一些非业务代码文件发布到 npm 中。 -
测试、构建相关的依赖请放入 devDependencies 字段中避免被一起打包到小程序包中。
改造已有包的约束
如果是已经发布过的一些 npm 包，因为一些原因无法改造成小程序 npm 包的结构的话，也可以通过微调后被使用，但是请确保遵循以下几点：
- 只支持纯 js 包，不支持自定义组件。
- 必须有入口文件，即需要保证 package.json 中的 main 字段是指向一个正确的入口，如果 package.json 中没有 main 字段，则以 npm 包根目录下的 index.js 作为入口文件。
- 测试、构建相关的依赖请放入 devDependencies 字段中避免被一起打包到小程序包中，这一点和小程序 npm 包的要求相同。
- 不支持依赖 c++ addon，不支持依赖 nodejs 的内置库：
const addon = require('./addon.node'); // 不支持！
const http = require('http'); // 不支持！
- 小程序环境比较特殊，一些全局变量（如 window 对象，document 对象）和构造器（如 Function 构造器）是无法使用的。
- 对于一些纯 js 实现的 nodejs 内置库（如 path 模块），可以通过额外安装其他开发者实现的 npm 包来支持。
- 此处使用 npm 包时如果只引入包名，则默认寻找包名下的 index.js 文件或者 index 组件。
- 使用 require 依赖的时候下列几种方式也是不允许的：
// 不允许将 require 赋值给其他变量后再使用，以下代码不会去解析出具体依赖
let r;
r = require;
r('testa');
let r2 = require;
r2('testa');
// 不允许 require 一个变量，以下代码依赖运行时，无法解析出具体依赖
let m = 'testa';
require(m);
进行发布
发布 npm 包流程可以参考这篇文章公共资源包发布流程详解
原理介绍
为了帮助大家更好的理解发布 npm 包中提到的各种要求，这里简单介绍一下原理：
- 首先 node_modules 目录中的代码不会参与小程序代码的编译、打包和上传，小程序仅能使用 npm 构建后形成的 miniprogram_npm 目录中的包。
- 构建打包分为两种：一种是：小程序 npm 包会直接拷贝构建后生成的目录文件（如在 package.json 文件中 miniprogram 指定为 dist）到 miniprogram_npm 中；另一种是：npm 包则会从入口 js 文件开始走一遍依赖分析和打包过程（类似 webpack）。
- 寻找小程序可用的 npm 包的过程和 常规 npm 的实现类似，从依赖 npm 包的文件所在目录开始逐层往外找，直到找到可用的 npm 包或是小程序根目录为止。
下面简单介绍下构建打包前后的目录情况。
构建之前的结构：
|--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
构建之后的结构：
|--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
{
"usingComponents": {
"a": "a"
}
}
其寻址顺序为
[
// 先寻址相对路径
"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”。
2169
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
