微信小程序工具 npm支持

npm 支持

從小程序基礎(chǔ)庫版本 2.2.1 或以上、及開發(fā)者工具 1.02.1808300 或以上開始，小程序支持使用 npm 安裝第三方包。

此文檔要求開發(fā)者們對(duì) npm 有一定的了解，因此不會(huì)再去介紹 npm 的基本功能。如若之前未接觸過 npm，請(qǐng)翻閱官方 npm 文檔進(jìn)行學(xué)習(xí)。

使用 npm 包

1. 在小程序中執(zhí)行命令安裝 npm 包：

npm install --production

此處并沒有強(qiáng)制要求 node_modules 必須在小程序根目錄下（即 project.config.js 中的 miniprogramRoot 字段），也可以存在于小程序根目錄下的各個(gè)子目錄中。但是不允許 node_modules 在小程序根目錄外。

PS：此處請(qǐng)務(wù)必使用--production選項(xiàng)，可以減少安裝一些業(yè)務(wù)無關(guān)的 npm 包，從而減少整個(gè)小程序包的大小。

1. 點(diǎn)擊開發(fā)者工具中的菜單欄：工具 --> 構(gòu)建 npm 
   
   
   
2. 勾選“使用 npm 模塊”選項(xiàng)： 
3. 構(gòu)建完成后即可使用 npm 包。

js 中引入 npm 包：

const package = require('packageName')
const packageOther = require('packageName/other')

使用 npm 包中的自定義組件：

{
  "usingComponents": {
    "package": "packageName",
    "package-other": "packageName/other"
  }
}

PS：此處使用 npm 包時(shí)如果只引入包名，則默認(rèn)尋找包名下的 index.js 文件或者 index 組件。

發(fā)布 npm 包

發(fā)布小程序 npm 包的約束

這里要發(fā)布的 npm 包是特指專為小程序定制的 npm 包（下稱小程序 npm 包）。因?yàn)樾〕绦蜃远x組件的特殊性，原有的 npm 包機(jī)制無法滿足我們的需求，所以這里需要對(duì)小程序 npm 包做一些約束：

1. 小程序 npm 包要求根目錄下必須有構(gòu)建文件生成目錄（默認(rèn)為 miniprogram_dist 目錄），此目錄可以通過在 package.json 文件中新增一個(gè) miniprogram 字段來指定，比如：

{
  "name": "miniprogram-custom-component",
  "version": "1.0.0",
  "description": "",
  "miniprogram": "dist",
  "devDependencies": {},
  "dependencies": {}
}

1. 小程序 npm 包里只有構(gòu)建文件生成目錄會(huì)被算入小程序包的占用空間，上傳小程序代碼時(shí)也只會(huì)上傳該目錄的代碼。如果小程序 npm 包有一些測(cè)試、構(gòu)建相關(guān)的代碼請(qǐng)放到構(gòu)建文件生成目錄外。另外也可以使用.npmignore文件來避免將一些非業(yè)務(wù)代碼文件發(fā)布到 npm 中。
2. 測(cè)試、構(gòu)建相關(guān)的依賴請(qǐng)放入 devDependencies 字段中避免被一起打包到小程序包中。

發(fā)布其他 npm 包的約束

如果是已經(jīng)發(fā)布過的一些 npm 包，因?yàn)橐恍┰驘o法改造成小程序 npm 包的結(jié)構(gòu)的話，也可以通過微調(diào)后被使用，但是請(qǐng)確保遵循以下幾點(diǎn)：

1. 只支持純 js 包，不支持自定義組件。
2. 必須有入口文件，即需要保證 package.json 中的 main 字段是指向一個(gè)正確的入口，如果 package.json 中沒有 main 字段，則以 npm 包根目錄下的 index.js 作為入口文件。
3. 測(cè)試、構(gòu)建相關(guān)的依賴請(qǐng)放入 devDependencies 字段中避免被一起打包到小程序包中，這一點(diǎn)和小程序 npm 包的要求相同。
4. 不支持依賴 c++ addon，不支持依賴 nodejs 的內(nèi)置庫：

const addon = require('./addon.node'); // 不支持！
const http = require('http'); // 不支持！

1. 使用 require 依賴的時(shí)候下列幾種方式也是不允許的：

// 不允許將 require 賦值給其他變量后再使用，以下代碼不會(huì)去解析出具體依賴
let r;
r = require;
r('testa');

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

// 不允許 require 一個(gè)變量，以下代碼依賴運(yùn)行時(shí)，無法解析出具體依賴
let m = 'testa';
require(m);

1. 小程序環(huán)境比較特殊，一些全局變量（如 window 對(duì)象）和構(gòu)造器（如 Function 構(gòu)造器）是無法使用的。

發(fā)布流程

發(fā)布 npm 包的流程簡(jiǎn)述如下：

1. 如果還沒有 npm 帳號(hào)，可以到 npm 官網(wǎng)注冊(cè)一個(gè) npm 帳號(hào)。
2. 在本地登錄 npm 帳號(hào)，在本地執(zhí)行：

npm adduser

或者

npm login

1. 在已完成編寫的 npm 包根目錄下執(zhí)行：

npm publish

到此，npm 包就成功發(fā)布到 npm 平臺(tái)了。

PS：一些開發(fā)者在開發(fā)過程中可能修改過 npm 的源，所以當(dāng)進(jìn)行登錄或發(fā)布時(shí)需要注意要將源切回 npm 的源。

原理介紹

為了幫助大家更好的理解發(fā)布 npm 包中提到的各種要求，這里簡(jiǎn)單介紹一下原理：

1. 首先 node_modules 目錄不會(huì)參與編譯、上傳和打包中，所以小程序想要使用 npm 包必須走一遍“構(gòu)建 npm”的過程，在最外層的 node_modules 的同級(jí)目錄下會(huì)生成一個(gè) miniprogram_npm 目錄，里面會(huì)存放構(gòu)建打包后的 npm 包，也就是小程序真正使用的 npm 包。
2. 構(gòu)建打包分為兩種：小程序 npm 包會(huì)直接拷貝構(gòu)建文件生成目錄下的所有文件到 miniprogram_npm 中；其他 npm 包則會(huì)從入口 js 文件開始走一遍依賴分析和打包過程（類似 webpack）。
3. 尋找 npm 包的過程和 npm 的實(shí)現(xiàn)類似，從依賴 npm 包的文件所在目錄開始逐層往外找，直到找到可用的 npm 包或是小程序根目錄為止。 下面簡(jiǎn)單介紹下構(gòu)建打包前后的目錄情況，構(gòu)建之前的結(jié)構(gòu)：

|--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

構(gòu)建之后的結(jié)構(gòu)：

|--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

PS：打包生成的代碼在同級(jí)目錄下會(huì)生成 source map 文件，方便進(jìn)行逆向調(diào)試。

js 模塊示例

以下為官方提供的 js 模塊，可以參考并使用：

• sm-crypto

自定義組件相關(guān)示例

請(qǐng)查閱開發(fā)第三方自定義組件文檔。