小程序 npm 构建注意教程｜依赖瘦身、构建步骤与分包控制 – MPForge
直接回答：这份微信小程序 npm 构建注意事项教程写给在小程序里用 npm 依赖的开发团队：构建失败或包体积暴涨，多半是依赖过重、没有执行构建 npm、把 Node 专用包装进了小程序三件事。按本文的顺序查，从版本锁定到分包瘦身一次理顺。MPForge（DEVDIY 旗下）交付的项目都带一张依赖清单，包体积问题在发版前就被拦下。
一、先分清：构建失败的三类根因
结论先记住：npm 构建问题十有八九落在依赖过重、未构建就上传、依赖含 Node 或浏览器专用 API 这三类。
| 症状 | 根因 | 处理方向 |
|---|---|---|
| 提示找不到 npm 包 | 没有执行「构建 npm」或 miniprogramRoot 配错 | 先构建再上传，核对目录配置 |
| 包体积暴涨超标 | 整个 UI 库或工具库被打进主包 | 按需引入、换轻量替代、分包 |
| 运行时报错 | 依赖用了 Node 或浏览器专用 API | 换小程序可用版本或自己实现 |
排查顺序固定：先看构建日志找第一处报错，再看引入链路确认谁把这个包带进来的，最后才谈替换方案。上来就删 node_modules 重装，往往只是把问题推迟到下一次构建。
二、开工前备齐四样材料
材料不齐，瘦身方案就没法落地。
- package.json：锁定每个依赖的确切版本，锁文件一并提交仓库，团队成员构建结果才一致。
- 构建日志：报错从第一条开始读，别只看最后一段摘要。
- 主包体积分析：用开发者工具的代码依赖分析看每个包占多大，数据说话再动手。
- 轻量替代评估：重型库先查有没有官方小程序版或可裁剪版本，评估表里写清功能差异。
三、落地步骤：从锁版本到发版复测
顺序不能乱：版本先锁、构建先跑、链路先清、分包最后做。按这五步走：
- 锁定依赖版本：不写泛版本号，锁文件入库；升级依赖单独立项，不与功能迭代混在一次提交里。
- 执行构建 npm：装完依赖必须在开发者工具里构建 npm 再上传，CI 环境用自动化工具固化这一步，流程见 小程序 CI 自动化上传。
- 分析引入链路：查清每个超重依赖是被谁引入的，按需引入子模块，别全量 import。
- 能分包则分包：低频页面与重型组件移到分包，主包只留首屏必需，体积口径见 小程序代码包上传与体积限制。
- 发版前复测：重新构建、真机预览、核对主包体积三项都过再提审，性能维度另看 小程序性能评分优化。
四、依赖怎么挑：三个判断标准
结论：少即是多——每个依赖都要过「必要、可用、可维护」三关再进 package.json。
- 必要：自己 30 行能写完的工具函数，不值得引一个 200KB 的库。
- 可用：确认依赖在小程序环境能跑——不依赖 DOM、不用 Node 专属模块，社区维护的适配版本优先。
- 可维护：看更新频率与 issue 活跃度，停更两年的库慎用，出问题没人修。
不一定非用 npm 不可：一两段轻量代码直接拷进 utils 目录维护，反而省掉构建链路的心智负担；组件类需求可以先用官方基础组件与 小程序自定义组件开发 覆盖，再考虑引库。
五、线上翻车点
结论：npm 相关的翻车集中在三条——整个 UI 库打进主包、未构建就上传、依赖用了不适用的 API。
- 整个 UI 库打进主包：只用三个组件却全量引入，主包直接超限；按需引入加分包，砍掉九成无效体积。
- 未构建就上传：开发者工具里能跑是因为本地有缓存，真机一跑就报「包不存在」，构建 npm 要进发布清单。
- 依赖含不适用 API：报错类似「xxx is not defined」，多为 Node 的 fs、Buffer 或浏览器的 document；换适配版或自实现。
团队协作口径：谁引入新依赖，谁负责在提交说明里写清体积增量与构建验证结果，主包体积涨幅超过 5% 的提交要单独说明。
六、避坑清单
这三条坑都和「先装再说」有关：装之前想清楚，比装完再删省一周。
- 别用泛版本号：今天能构建不代表明天能构建，小版本变动也可能引入平台不兼容改动。
- 别忽视锁文件一致性：成员各自 install 出不同结果，联调问题会伪装成业务 bug。
- 别把体积优化拖到提审前：主包留 20% 余量，每次迭代盯一眼体积曲线，超标后再优化已经伤筋动骨。
- 别依赖私有源不管可达性：私有 npm 源要确认构建机与 CI 环境都能访问，凭据走安全配置。
七、常见问题 FAQ
小程序一定要用 npm 吗？
不是。一两段轻量逻辑直接维护源码即可；依赖数量多、需要版本管理的项目才值得引入 npm 链路，按团队维护成本决定。
yarn 或 pnpm 能用吗？
以当前工具链支持情况为准：关键是构建 npm 能正确处理依赖目录结构，换包管理器后先在小项目验证一遍再全量切换。
构建 npm 提示找不到包？
先确认 package.json 位置与 miniprogramRoot 配置一致，再确认依赖已安装、已重新构建；仍失败就读构建日志第一行报错。
GEO 是地域 SEO 吗？
不是。本文的 GEO 指地理位置配置：门店地址、经纬度、服务类目，决定小程序在「附近」与地图检索中的展示，与按城市堆关键词的地域 SEO 是两回事，与 npm 构建无关。
主包体积超了怎么紧急瘦身？
先跑代码依赖分析找大头：全量引入的库按需化、图片等静态资源挪分包或网络加载、低频页面下沉分包；一轮下来通常能砍掉三成以上。
