小程序如何使用 npm 包和第三方组件库？有哪些限制？

简化版

小程序可以使用 npm 包，但需要经过开发者工具或构建工具的 npm 构建流程，并在页面或组件 JSON 的 usingComponents 中声明组件路径。注意不是所有 Web npm 包都能用，依赖 DOM、BOM、Node API、动态执行代码的包通常不适合小程序环境。

详细版

常见流程：

npm install 安装依赖。
在开发者工具中构建 npm，生成 miniprogram_npm。
在页面、组件或全局 JSON 中配置 usingComponents。
在 WXML 中使用组件标签。

{
  "usingComponents": {
    "van-button": "@vant/weapp/button/index"
  }
}

限制主要来自小程序运行环境：没有浏览器 DOM，不能随便访问 window/document；包体积要控制；组件库要按需引入；依赖链要审计，避免把无用代码和不安全包带入小程序包。

完整版教学

一、小程序支持 npm，但不是直接照搬 Web

很多同学以为小程序支持 npm 后，就能像 Web 项目一样随意安装包。实际上，小程序的 npm 支持需要适配它自己的包构建和运行环境。

安装 npm 包
  -> 构建 npm
  -> 生成 miniprogram_npm
  -> usingComponents 引用
  -> WXML 使用组件

小程序不是浏览器页面，没有完整 DOM、BOM，也没有 Node.js 运行时。一个依赖 window.document 的 UI 包，在 Web 里能跑，在小程序里可能直接报错。

因此面试回答要强调“npm 是包管理方式，不代表运行能力完全相同”。能不能用一个包，取决于它是否适配小程序环境。

二、第三方组件库通常通过 usingComponents 引入

组件库安装后，页面或组件需要在 JSON 中声明要使用的组件。声明之后，WXML 才能识别对应标签。

{
  "usingComponents": {
    "t-button": "tdesign-miniprogram/button/button",
    "van-cell": "@vant/weapp/cell/index"
  }
}

<t-button theme="primary">提交</t-button>
<van-cell title="订单号" value="{{orderNo}}" />

如果 20 个页面都使用同一个组件，可以考虑全局注册；如果只有某个页面使用，局部注册更利于控制依赖和包体积。

注册位置	优点	风险
全局 app.json	使用方便	可能增加主包体积
页面 json	按页面控制	多页面重复声明
组件 json	封装更清楚	依赖关系要维护

工程里通常按需引入，而不是整库全量引入。小程序包体积限制比 Web 更敏感。

三、构建 npm 的产物要进入小程序包管理

小程序开发者工具会把 npm 依赖处理成小程序可识别的结构，常见生成目录是 miniprogram_npm。如果团队使用 CLI 或跨端框架，也会有类似构建步骤。

node_modules
  -> 构建处理
  -> miniprogram_npm
  -> 小程序编译上传

这里有两个常见坑。第一，本地安装了依赖但忘记构建 npm，页面找不到组件。第二，构建产物、依赖版本和锁文件在团队之间不一致，导致有人能运行、有人不能运行。

假设组件库版本从 1.8.0 升到 1.9.0，一个页面 API 改了，如果锁文件没提交或构建产物不一致，就可能出现“开发者 A 正常、开发者 B 报错”的情况。

四、不是所有 npm 包都适合小程序

判断一个包能否用于小程序，可以看它依赖什么运行能力。纯函数工具库通常容易适配，浏览器 DOM 操作库、Node 内置模块库、动态代码执行库通常风险较高。

包类型	小程序适配概率	原因
日期、数字、纯函数工具	高	不依赖宿主环境
小程序专用组件库	高	已适配 WXML/WXSS
Web DOM UI 库	低	依赖 DOM/BOM
Node 服务端库	低	依赖 fs、path、http 等
大型全量 SDK	中低	体积和环境依赖不确定

例如 lodash-es 的某些纯函数可以用，但一个依赖 document.createElement 的弹窗库不能直接用。面试时能说出“看运行环境依赖”，比只说“npm 包能用”更准确。

记忆钩子：小程序支持 npm 是“支持包管理”，不是“支持浏览器和 Node 的所有能力”。

五、包体积和分包策略要一起考虑

小程序上传和运行对包体积敏感，组件库、图标库、SDK 很容易撑大主包。引入 npm 包时，要关心它进入主包还是分包。

主包：启动必需页面、tabBar、公共基础代码
分包：低频页面、业务模块、可延后加载的组件

假设一个组件库全量 800 KB，只在售后页面使用，而售后页面在分包中。如果把组件全局注册进主包，所有用户启动时都要为低频功能付出代价。更合理的是在售后分包内局部引用。

体积优化常见手段包括按需引入、删除无用组件、压缩图片、使用分包、减少重复依赖和审查构建产物。

六、依赖安全和可维护性不能忽略

小程序代码运行在客户端，用户可以反编译和观察请求。npm 依赖一旦进入包内，也属于可见代码。不能把 AppSecret、私钥、后端密钥放进依赖或配置里。

依赖引入前
  -> 看是否适配小程序
  -> 看包体积
  -> 看维护状态
  -> 看许可证
  -> 看是否有敏感逻辑

第三方组件库还会影响 UI 一致性和升级成本。组件库主版本升级可能带来样式、事件名、属性名变化。工程上应锁定版本、写升级记录，并在关键页面回归。

如果一个项目有 30 个页面依赖组件库，升级前至少要覆盖核心链路：登录、下单、支付、表单、列表、弹窗。否则一个按钮属性变更就可能造成线上提交失败。

七、常见误区与追问

误区：小程序支持 npm，所以所有 npm 包都能用。 运行环境不支持完整 DOM、BOM 和 Node API，很多包不能直接用。
误区：安装 npm 包后马上能在 WXML 用。 通常还需要构建 npm，并在 JSON 中配置 usingComponents。
误区：组件全局注册最省事。 全局注册可能增加主包体积，低频组件应考虑局部引入或分包。
追问：为什么 Web UI 库不能直接用？ 它们通常依赖 DOM、CSSOM、浏览器事件和渲染机制，小程序没有这些完整能力。
追问：如何控制组件库体积？ 按需引入、局部注册、分包放置、审查构建产物和删除无用依赖。
追问：npm 依赖安全看什么？ 看维护状态、漏洞、许可证、是否夹带敏感逻辑，以及是否把密钥打进客户端包。

八、加强记忆

小程序 npm 题按“安装、构建、声明、限制、体积、安全”记：装包不是结束，要构建 npm；组件要 usingComponents；能不能用看环境依赖；好不好用看体积和维护；安不安全看是否把敏感能力放进客户端。

简化版

详细版