微信小程序使用 npm 包

一、前言：为什么小程序也能用 npm？

你是否还在：

• 手动复制 lodash 源码到项目中？
• 自己封装日期格式化函数？
• 重复造轮子处理防抖、深拷贝等通用逻辑？

好消息：微信小程序自基础库 2.2.1 起，正式支持使用 npm 包！

通过官方提供的 “构建 npm” 功能，你可以像在 Vue/React 中一样，直接 npm install 安装第三方库，大幅提升开发效率和代码质量。

本文将手把手教你在小程序中正确使用 npm 包，并避开通往“构建失败”的坑。

二、前提条件

✅ 小程序基础库 ≥ 2.2.1（当前最新版已默认满足） ✅ 开发者工具 ≥ 1.02.1810290（建议使用最新稳定版） ✅ 项目已启用 “使用 npm 模块”（新版工具默认开启）

💡 打开开发者工具 → 详情 → 项目设置 → 勾选 “使用 npm 模块”

三、完整操作流程（以 dayjs 为例）

第一步：初始化 package.json（如果还没有）

在小程序项目根目录下执行：

npm init -y

会生成 package.json 文件。

第二步：安装 npm 包

npm install dayjs –save

⚠️ 注意：

• 不要安装浏览器或 Node.js 专用包（如 fs, path）
• 优先选择 轻量、无 DOM 依赖 的库（如 dayjs 优于 moment）

第三步：在代码中引入

// pages/index/index.js
import dayjs from 'dayjs';

Page({
onLoad() {
const now = dayjs().format('YYYY-MM-DD HH:mm:ss');
console.log('当前时间:', now);
this.setData({ currentTime: now });
}
});

第四步：【关键】点击开发者工具 → 工具 → 构建 npm

🔑 必须执行此步骤！否则会报错：

Module not found: Can't resolve 'dayjs'

构建成功后，项目根目录会生成 miniprogram_npm 文件夹，里面是经过转换的 npm 包。

第五步：真机调试 & 预览

• 开发者工具模拟器：通常可直接运行
• 真机预览/上传：必须先构建 npm，否则真机会白屏或报错

四、支持哪些 npm 包？

✅ 推荐使用（兼容性好）：

❌ 不支持（慎用）：

• 依赖 window、document 等浏览器 API 的包
• 依赖 Node.js 内置模块（如 fs, crypto）
• 使用动态 require() 或复杂 Webpack 配置的库

💡 技巧：可先在 unpkg.com 查看包源码，确认无环境依赖

五、常见问题与解决方案

❌ 问题 1：构建 npm 后仍报 “module not found”

原因：

• 未正确执行“构建 npm”
• 引入路径错误

解决：

❌ 问题 2：npm 包体积过大，影响小程序包大小

现象： miniprogram_npm 占用几百 KB，接近 2MB 主包限制

优化方案：

❌ 问题 3：使用 TypeScript 时报类型错误

解决： 安装对应 @types（如果存在）：

npm install @types/lodash –save-dev

并在 tsconfig.json 中配置：

{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"*": ["miniprogram_npm/*"]
}
}
}

六、高级技巧：发布自己的 npm 组件包

如果你封装了一套通用组件（如 my-ui），也可发布为 npm 包供团队使用：

📌 官方文档：小程序 npm 支持规范

七、最佳实践建议

八、结语

感谢您的阅读！如果你有任何疑问或想要分享的经验，请在评论区留言交流！