npm 能力
npm 能力从基础库版本 2.12.0 开始支持，IDE 版本 3.1.1 开始支持。
在字节小程序中，npm 包分为两种类型：
类型 | 特点 |
|---|---|
普通 npm 包 | 和 官方 npm 相比，此类型的 npm 包多了一些限制，具体可参考开发 npm 中限制 |
小程序 npm 包 | 和普通 npm 包相比，小程序 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 打包构建
IDE 工具提供 npm 打包构建能力，使用步骤如下
- 进入小程序，完成 “npm init” 和 “npm install”
- 编辑器“侧边栏”打开 NPM 模块
- 点击“构建 NPM”按钮
构建完成使用 npm
在自定义组件以及路由跳转场景，需要使用特殊的路径 "ext://myNpm/index"
token | 含义 |
|---|---|
ext:// | 标识要使用 node_modules 中的自定义组件或者页面 |
myNpm | 标识 package.json 或者 node_modules 中的包名 |
index | 是 alias 的含义，通过这个 index 字符串，从 npm 包的 package.json 中的 exports.components 或者 exports.pages 字段映射到一个真实的路径 |
使用 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:// 协议头 + 小程序页面路径，这个路径一般由小程序 npm 使用者传入，是在 app.json 中 pages 定义的路径
tt.navigateTo(`usr://${pagepath}`);使用本地资源
开发 npm 包时，可能需要使用到小程序的某些媒体组件（image、video 组件），如果组件依赖于用户传递资源地址，需要注意以下两种路径的差异：
类型 | 使用方式 |
|---|---|
在线路径 | 正常使用 |
本地路径 | 需要使用 |
{
"usingComponents": {
"component_npm": "ext://name/"
}
}<!-- index.ttml 中使用 -->
<!-- 使用小程序 npm 组件，传入本地图片路径 -->
<component_npm url="usr://path/to/index"></component_npm>作为 npm 包开发者，建议在 readme.md 中提示 npm 包使用者通过 usr:// 自定义协议头方式传入本地路径。
开发限制
小程序 npm 和普通 npm 通用限制：
- 不支持依赖 c++ addon
- 不支持依赖 nodejs 的内置库
- 不支持动态 require 直接 require 一个变量 将 require 赋值给变量，通过变量 require
- 不支持使用全局变量（如 window 对象）和构造器（如 Function 构造器）
- 避免非产物依赖被打包到小程序包中 无关代码放在 生成目录外 放在 devDependencies 中，避免被打包，增大使用者的包体积。 使用 .npmignore 文件来避免将一些非业务代码文件发布到 npm 中
小程序 npm
- 必须指定导出目标
即需要保证 package.json 中指定 exports 目标，若为空，则该依赖的打包产物为空，使用时引用不到该文件
- 第三方平台如果支持使用 npm 作为 page 的话，需要开发者把 npm 的 page 路径加入 ext.json 的 pages 字段中
- miniprogramType 必须指定为 tt-npm
{
"name": "myNpm", // npm 名称
"miniprogramType": "tt-npm",
// 需要导出的js，路径为相对 src 目录
"main": "src/index",
"exports": {
// 需要导出的页面，路径为相对 src 目录，不指定则构建时不会打包
"pages": {
"myPage": "pages/index"
},
// 需要导出的自定义组件，路径为相对 src 目录，不指定则构建时不会打包
"components": {
"myComp": "components/index"
}
}
}与部分小程序框架处理 dist 目录的方式不同，它们在处理小程序 npm 的场景，会直接把 dist 目录拷贝到 miniprogram_npm 下。但是在字节小程序的场景需要增加 miniprogramType 以及 exports 字段，而且我们不是简单的拷贝，会把 main 指向的 js 以及 exports 中的页面和组件的 js 打包一次。
普通 npm
- 必须有入口文件
即需要保证 package.json 中的 main 字段是指向一个正确的入口，如果 package.json 中没有 main 字段，则以 npm 包根目录下的 index.js 作为入口文件。