npm 能力
npm 能力从基础库版本 2.12.0 开始支持,开发者工具从版本 3.1.1 开始支持。
在字节小程序中,npm 包分为两种类型:
类型 | 特点 |
---|---|
普通 npm 包 | 和 官方 npm 相比,此类型的 npm 包多了一些限制,具体可参考开发 npm 中限制 |
小程序 npm 包 | 和普通 npm 包相比,小程序 npm 增加了如下几个能力: |
使用 npm
在开发者工具的编辑器侧边栏中激活 NPM 功能的面板。

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

刚初始化的 package.json
中是没有依赖的,面板中提供了快捷功能,方便开发者进行依赖的安装。
安装 npm 依赖
鼠标悬浮在 “运行依赖” 的条目上时,点击 “+” 号按钮,在弹出的对话框中输入依赖名称和版本号安装运行依赖 dependencies
。输入格式应当为 <package>@version
,其中 version
可选,不填时会使用最新版本 latest
。
下图以 is-number
为例。

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

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

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

- npm 构建:构建 npm 包到
miniprogram_npm
目录下,以供小程序代码使用。 - 刷新依赖状态:面板列表的状态跟当前文件目录内容不同步时,可以手动进行状态更新。
- 打开
package.json
:在编辑器中快捷打开小程序目录下的package.json
文件。 - 安装所有依赖:在
package.json
文件所在的目录,安装所有的依赖。 - 卸载所有依赖:在
package.json
文件所在的目录,删除node_modules
目录。 - 打开日志:在 “输出” 面板打开 npm 功能的命令执行的记录。
npm 构建
当前在开发者工具中,有两处可以调用 npm 构建的功能。
- npm 功能的面板的顶部点击 “npm 构建” 按钮。
- 通过 “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
。
token | 含义 |
---|---|
ext:// | 标识要使用 |
myNpm | 标识 |
index | 是 alias 的含义,通过这个 |
使用 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 的使用限制
- 不支持依赖 C++ addon 。
- 不支持依赖 nodejs 的内置库。
-
不支持动态 require 调用,会引起依赖解析错误,举例如下:
// 不支持直接 require 一个变量 const myModule = "myModule"; require(myModule); // 不支持将 require 赋值给变量后进行调用 const myRequire = require; myRequire("module");
- 小程序运行环境限制,不支持使用部分全局变量(如
window
对象)和构造器(如Function
构造器)等。 - 避免非产物依赖被打包到小程序包中,无关代码放在生成目录外,构建、测试等非运行时依赖放在
devDependencies
中,避免被打包。 推荐使用.npmignore
文件来避免将一些非业务代码文件发布到 npm 中。
小程序 npm 的使用要求
-
必须指定导出目标。
即需要保证
package.json
中指定exports
目标,若为空,则该依赖的打包产物为空,使用时引用不到该文件。 - 第三方平台如果支持使用 npm 作为
page
的话,需要开发者把 npm 的page
路径加入ext.json
的pages
字段中。 -
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 的使用要求
-
必须有入口文件
即需要保证
package.json
中的main
字段是指向一个正确的入口,如果package.json
中没有main
字段,则以 npm 包根目录下的index.js
作为入口文件。在开发者工具 “构建 NPM” 时,会以该入口 js 文件为起点进行依赖分析和打包构建(可类比 webpack 的构建流程)。