微信小程序使用 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 包？

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

包名	用途
dayjs	日期处理（比 moment 轻 90%）
lodash-es	工具函数（需注意 tree-shaking）
uuid	生成唯一 ID
qs	URL 参数解析
axios-miniprogram-adapter	在小程序中使用 axios

❌ 不支持（慎用）：

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

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

---

五、常见问题与解决方案

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

原因：

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

解决：

1. 确保 miniprogram_npm 文件夹存在

2. 引入时不要加 .js 后缀 ：

   // ✅ 正确
   import dayjs from 'dayjs';
   
   // ❌ 错误
   import dayjs from 'dayjs/index.js';

---

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

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

优化方案：

1. 按需引入 （以 lodash 为例）：

   // ❌ 全量引入（不推荐）
   import _ from 'lodash';
   
   // ✅ 按需引入
   import debounce from 'lodash/debounce';
   import cloneDeep from 'lodash/cloneDeep';

2. 使用更轻量替代品（如 dayjs 替代 moment）

---

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

解决 ：

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

npm install @types/lodash --save-dev

并在 tsconfig.json 中配置：

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

---

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

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

1. 在组件包根目录添加 miniprogram 字段（package.json）：

   {
     "name": "my-mini-ui",
     "version": "1.0.0",
     "miniprogram": "dist"  // 指向小程序组件目录
   }

2. 发布到 npm：

   npm publish

3. 其他项目安装后，同样执行 构建 npm 即可使用

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

---

七、最佳实践建议

1. 定期清理无用依赖 ：npm prune
2. 锁定版本 ：使用 package-lock.json 避免依赖漂移
3. 主包瘦身：将 npm 包放在分包中（需基础库 ≥ 2.11.0）
4. 避免深层嵌套依赖：优先选择零依赖的小工具库

---

八、结语

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