前提条件
- 微信开发者工具
确保安装最新版本（官网下载）,并登录小程序账号。 - 初始化项目
项目根目录需存在package.json文件（若无，通过终端执行npm init -y生成）。 - 小程序配置
在project.config.json中启用npm支持：{ "setting": { "packNpmManually": true, // 手动构建npm "packNpmRelationList": [ // 指定需构建的模块 { "packageJsonPath": "./package.json", "miniprogramNpmDistDir": "./miniprogram/" } ] } }
执行 npm 命令的完整流程
步骤1：安装依赖
在项目根目录打开终端（或微信开发者工具的终端）,执行安装命令：
npm install lodash # 示例：安装 lodash
- 依赖会写入
package.json的dependencies字段。 - 安装后生成
node_modules目录（切勿直接调用其中的代码）。
步骤2：构建 npm 模块
- 手动构建（推荐）
- 在微信开发者工具顶部菜单点击 工具 → 构建 npm。
- 构建成功后生成
miniprogram_npm目录（存放小程序可用的依赖包）。
- 自动构建
修改project.config.json：{ "setting": { "packNpmManually": false // 关闭手动模式（每次保存自动构建） } }
步骤3：引入模块使用
在 JS 文件中按路径引入：
// 正确引入方式（从 miniprogram_npm 目录加载）
const _ = require('lodash');
_.chunk(['a', 'b', 'c'], 2); // 使用模块功能
常见问题解决
-
构建失败：模块未找到
- 检查
package.json中依赖名称是否拼写错误。 - 删除
node_modules和miniprogram_npm后重新npm install并构建。
- 检查
-
代码报错：依赖不兼容
- 小程序仅支持纯 JS 包（不支持 Node.js 或浏览器环境 API）。
- 通过小程序 npm 支持列表确认兼容性。
-
TypeScript 支持
在tsconfig.json中添加路径映射：{ "compilerOptions": { "baseUrl": ".", "paths": { "*": ["./miniprogram_npm/*"] } } }
关键注意事项
- 路径规范
- 所有 npm 模块必须通过
miniprogram_npm引入，直接引用node_modules会导致上线失败。
- 所有 npm 模块必须通过
- 依赖限制
- 禁止安装含原生组件、C++ 插件的包（如
canvas）。 - 包体积需符合小程序 2MB 限制（分包可扩展至 20MB）。
- 禁止安装含原生组件、C++ 插件的包（如
- 版本管理
- 锁定版本号（如
lodash@4.17.21）避免自动升级导致兼容问题。
- 锁定版本号（如
- 自定义组件
若使用 npm 中的自定义组件，需在json文件中声明：{ "usingComponents": { "my-component": "module-name" } }
正确执行 npm 命令能显著提升小程序的开发效率，但必须遵循微信的构建规范,重点在于：
- 通过 构建 npm 生成
miniprogram_npm目录； - 始终从
miniprogram_npm引入依赖； - 定期检查包兼容性与体积。
如遇复杂问题，优先查阅微信官方 npm 文档,或通过开发者社区反馈。
引用说明依据微信官方文档《小程序使用 npm》整理，实践过程已通过微信开发者工具 v1.06.2303220 验证（2025年10月）。
原创文章，发布者：酷番叔，转转请注明出处：https://cloud.kd.cn/ask/8938.html
