npm 能力

npm 能力从基础库版本 2.12.0 开始支持，IDE 版本 3.1.1 开始支持。

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

使用 npm

安装 npm

在小程序 package.json 所在的目录中执行命令安装 npm 包：

npm install

限制

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

npm 打包构建

字节小程序开发者工具提供 npm 打包构建能力，使用步骤如下

• 进入小程序，完成 “npm init” 和 “npm install”
• 编辑器 “侧边栏” 打开 NPM 模块的面板
• 点击 “构建 NPM” 按钮

查看原图

构建完成使用 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 的占比是否符合预期。