npm 在小程序里怎么用

小程序支持 npm 包，但不是直接把 node_modules 塞进代码里用。开发者工具提供了一个「构建 npm」的功能，会把用到的包编译成小程序能跑的产物，生成到 miniprogram_npm 目录，页面再用 require 引进来。

这套流程的本质是：本地开发照常 npm install 装依赖，构建时工具帮你把包从 CommonJS 编译成小程序运行时认得的模块。所以 package.json 和 node_modules 在小程序工程里一样存在，只是多了一步构建。

理解了这一步，后面所有依赖管理、组件复用、版本升级都好办。下面从引入第一个三方包开始。

本文核心知识点
  • 构建npm 构建生成 miniprogram_npm。
  • 依赖package.json 管理三方包。
  • 组件自建组件打成私有包。
  • 复用语义化版本与升级策略。
小程序 npm 与组件化配图：蓝调渐变背景上多个模块方块经构建箭头汇入一个统一的组件库的扁平科技插画
依赖和组件统一收进工程，构建一次，处处复用。

引入三方依赖

在项目根目录执行 npm install，把包装进 node_modules，然后在开发者工具里点「工具 - 构建 npm」，构建完项目里会出现 miniprogram_npm 目录。页面里这样引用：

// 页面脚本里引入 npm 包
var md5 = require('miniprogram-md5');
var hash = md5('吉极云码');

// 或用 ES 模块写法
import dayjs from 'dayjs';
var now = dayjs().format('YYYY-MM-DD HH:mm:ss');

注意只有 package.json 里声明了 dependencies 的包才会被构建。devDependencies 里的一般是构建工具，不会进小程序产物，别把运行时依赖误放在 devDependencies 里。

构建完如果包没有出现在 miniprogram_npm，先看工具的构建日志，常见原因是包不支持小程序环境，或者包的入口文件用了浏览器专用 API。选包时优先挑标注支持小程序或跨端框架的库。

自建组件与私有包

项目里重复的 UI 和逻辑，都可以抽成自定义组件。组件目录里放 json、wxml、wxss、js 四个文件，页面里 usingComponents 注册就能用。组件多了，就要考虑跨项目复用：把组件打成 npm 包发布到私有仓库。

私有包的发布流程和公开包一样：写好 package.json、跑 npm pack 本地验证、再 npm publish 到公司私服。消费方装包时指定版本，构建 npm 后即可使用组件。

// package.json 里约定组件包的基本信息
{
  "name": "@company/miniapp-ui",
  "version": "1.4.0",
  "main": "index.js",
  "miniprogram": "miniprogram_dist"
}

组件包发布前，最好先构建出 miniprogram_dist 目录再打进去，避免把源码直接暴露给下游。包里的组件 json 要声明 component 为 true，消费方才认得它是组件。

版本管理与复用

npm 的语义化版本号在小程序工程里同样适用：主版本号不兼容变更、次版本号加功能、修订号修 bug。消费方锁版本要讲究，线上项目别用 latest 或通配符，出问题不好回滚。

变更类型版本示例说明
修 bug1.4.0 → 1.4.1无感升级
加功能1.4.1 → 1.5.0向后兼容
破坏性变更1.5.0 → 2.0.0需评估改造

升级组件包之前，先看 CHANGELOG，重点确认有没有破坏性变更，再决定是整体升级还是先升级一两个页面试用。npm 可以装指定版本，比如 npm install @company/miniapp-ui@1.4.1，需要回退时直接改回旧版本号重装。

多项目复用同一个组件包时，建议统一在 README 里维护使用说明和版本对照表，避免每个项目各记一套用法。

依赖升级也有讲究：安全补丁要跟，功能性大版本先小范围灰度。小程序端 npm 升级后必须重新构建，光改 package.json 不点构建，线上跑的还是旧产物。

工程化配套

组件多了以后，光靠自觉不够，要配一些工程化手段：目录规范约定好组件放哪、页面放哪；ESLint 管代码风格；组件文档跟着包走，写清楚 props 和事件。

组件化的价值不在组件本身，而在约定：谁来用、怎么用、坏了谁修。

还可以在 CI 里加一步：push 后自动跑组件包的单元测试和构建，构建失败就不允许合入，把问题挡在发布之前。

组件文档别只写用法，把边界条件也写清楚：什么情况下组件会怎样表现、已知限制是什么。文档跟着包版本走，消费方查一个版本只看一份文档，不会翻错。