npm 能力

npm 能力从基础库版本 2.12.0 开始支持，开发者工具从版本 3.1.1 开始支持。

在字节小程序中，npm 包分为两种类型：

使用 npm

在开发者工具的编辑器侧边栏中激活 NPM 功能的面板。

查看原图

初始化 package.json

对于没有使用过 npm 功能的小程序项目，可以直接点击提示按钮，完成 package.json 文件的初始化。面板中 “运行依赖” 对应 package.json 中的 dependencies ，“开发依赖” 对应 devDependencies 。

查看原图

刚初始化的 package.json 中是没有依赖的，面板中提供了快捷功能，方便开发者进行依赖的安装。

安装 npm 依赖

鼠标悬浮在 “运行依赖” 的条目上时，点击 “+” 号按钮，在弹出的对话框中输入依赖名称和版本号安装运行依赖 dependencies 。输入格式应当为 <package>@version ，其中 version 可选，不填时会使用最新版本 latest 。

下图以 is-number 为例。

查看原图

同样地，开发者可以通过 “开发依赖” 条目上的 “+” 号按钮安装开发依赖devDependencies。

查看原图

另外，对于单个依赖的安装和卸载，可以根据该条目右侧的按钮进行快捷操作。

查看原图

面板的顶部提供了更多的功能：

查看原图

1. npm 构建：构建 npm 包到 miniprogram_npm 目录下，以供小程序代码使用。
2. 刷新依赖状态：面板列表的状态跟当前文件目录内容不同步时，可以手动进行状态更新。
3. 打开 package.json：在编辑器中快捷打开小程序目录下的 package.json 文件。
4. 安装所有依赖：在 package.json 文件所在的目录，安装所有的依赖。
5. 卸载所有依赖：在 package.json 文件所在的目录，删除 node_modules 目录。
6. 打开日志：在 “输出” 面板打开 npm 功能的命令执行的记录。

npm 构建

当前在开发者工具中，有两处可以调用 npm 构建的功能。

1. npm 功能的面板的顶部点击 “npm 构建” 按钮。
2. 通过 “F1” 调起菜单面板，搜索 “npm 构建” 。

查看原图

任选其一即可进行 npm 构建，产物会在小程序项目下的 miniprogram_npm 目录。

进行构建时会有一些限制：

• 参与构建 npm 的 package.json 需要在 project.config.json 定义的 miniprogramRoot 之内。 miniprogramRoot 字段不存在时，miniprogramRoot 指向的就是 project.config.json 所在的目录。
• 打包构建 npm 依赖时根据 package.json 的 dependencies 字段。 devDependencies 里的依赖也可以在开发过程中被安装使用而不会参与到构建中。

构建完成使用 npm

在自定义组件以及路由跳转场景，需要使用特殊的路径 ext://myNpm/index 。

使用 npm 中的 js

支持引用普通 npm 包和小程序 npm 。

// 直接引用包名
const myNpm = require("myNpm");

const myNpmOther = require("myNpm/other");

使用 npm 中的自定义组件

引用时，必须指定特殊协议头 ext:// 。

如下是使用小程序 npm 自定义组件的例子：

// 直接引用小程序 npm 名
{
  "usingComponents": {
    "component_npm": "ext://xxname/xxroute"
  }
}

<component_npm></component_npm>

路由跳转场景

组件跳转

通过 navigator 组件跳转小程序 npm 页面。

<navigator url="ext://myNpm/index">
  <button>跳转到npm页面</button>
</navigator>

API 跳转

通过 tt.navigateTo，tt.redirectTo 等 api 进行跳转。

// page.js
Page({
  onClick() {
    tt.navigateTo({
      url: "ext://myNpm/index",
    });
  },
});

开发 npm

普通 npm

即纯 js 包，同 npm 官方流程，见 npm 官方文档 。

小程序 npm

既可以用来作为 component、page，也可用作普通 npm。针对小程序 npm 组件、页面与外部交互的场景，字节小程序提供了 usr:// 自定义协议头。

从 npm 内部跳转小程序

npm 跳转小程序路由符合 “协议头 + 小程序页面路径” 的格式（usr://${pagePath}），这个路径一般由小程序 npm 使用者传入，是在 app.json 中 pages 定义的路径。

tt.navigateTo(`usr://${pagePath}`);

使用本地资源

开发 npm 包时，可能需要使用到小程序的某些媒体组件（image、video 组件），如果组件依赖于用户传递资源地址，需要注意以下两种路径的差异：

下面以 image 组件接受本地资源路径为例：

{
  "usingComponents": {
    "component_npm": "ext://name/"
  }
}

<!-- index.ttml 中使用 -->
<!-- 使用小程序 npm 组件，传入本地图片路径 -->
<component_npm url="usr://path/to/index"></component_npm>

作为 npm 包开发者，建议在 README.md 中提示 npm 包使用者通过 usr:// 自定义协议头方式传入本地路径。

开发限制

小程序 npm 的使用限制

1. 不支持依赖 C++ addon 。
2. 不支持依赖 nodejs 的内置库。

3. 不支持动态 require 调用，会引起依赖解析错误，举例如下：

   // 不支持直接 require 一个变量
   const myModule = "myModule";
   require(myModule);
   
   // 不支持将 require 赋值给变量后进行调用
   const myRequire = require;
   myRequire("module");

4. 小程序运行环境限制，不支持使用部分全局变量（如 window 对象）和构造器（如 Function 构造器）等。
5. 避免非产物依赖被打包到小程序包中，无关代码放在生成目录外，构建、测试等非运行时依赖放在 devDependencies 中，避免被打包。 推荐使用 .npmignore 文件来避免将一些非业务代码文件发布到 npm 中。

小程序 npm 的使用要求

1. 必须指定导出目标。

   即需要保证 package.json 中指定 exports 目标，若为空，则该依赖的打包产物为空，使用时引用不到该文件。

2. 第三方平台如果支持使用 npm 作为 page 的话，需要开发者把 npm 的 page 路径加入 ext.json 的 pages 字段中。

3. miniprogramType 必须指定为 "tt-npm"。

   {
     // npm 名称
     "name": "myNpm",
     "miniprogramType": "tt-npm",
     // 需要导出的js，路径为相对 src 目录
     "main": "src/index",
     "exports": {
       // 需要导出的页面，路径为相对 src 目录，不指定则构建时不会打包
       "pages": {
         "myPage": "pages/index"
       },
       // 需要导出的自定义组件，路径为相对 src 目录，不指定则构建时不会打包
       "components": {
         "myComp": "components/index"
       }
     }
   }

   部分现行小程序框架在处理小程序 npm 的场景时，会直接把 dist 目录拷贝到 miniprogram_npm 下。

   但是在字节小程序的场景需要增加 miniprogramType 以及 exports 字段，而且不是简单的文件拷贝，而是会把 main 指向的入口 js 文件以及 exports 中的页面和组件的 js 文件作为入口进行构建。

普通 npm 的使用要求

1. 必须有入口文件

   即需要保证 package.json 中的 main 字段是指向一个正确的入口，如果 package.json 中没有 main 字段，则以 npm 包根目录下的 index.js 作为入口文件。

   在开发者工具 “构建 NPM” 时，会以该入口 js 文件为起点进行依赖分析和打包构建（可类比 webpack 的构建流程）。

Bug & Tip

• Tip：npm 能力在基础库 2.12.0 以上版本才开始支持，因此开发者需要在开发者后台指定最低基础库版本为 2.12.0，保证小程序不会运行在低版本基础库上。

  截止到 2021/8/20 日， 2.12.0 以及以上的基础库版本在抖音上占比达到 93% 左右。请注意，指定了最低基础库版本会导致 小程序 在低于此版本基础库的宿主上不可见，目前非抖音、头条的 APP 接入的基础库版本都会比较低，所以接入非抖音、头条 APP 的开发者需要关注 2.12.0 以上基础库在这些 APP 的占比是否符合预期。