必须手动触发微信开发者工具的「构建 npm」，否则 import 报错；该步骤生成 miniprogram_npm 目录供小程序识别，且每次修改 package.json 后都需重新构建。
不能直接 import 就完事，微信小程序平台不读 node_modules，必须走「构建 npm」流程，否则 90% 概率报 Cannot read property 'document' of undefined 或 global is not defined。
npm install 后 import 报错：没触发构建或包本身不兼容
微信开发者工具不会自动扫描 node_modules，它只认 miniprogram_npm/ 目录下的内容。即使 npm install 成功、package.json 里有依赖，不点「构建 npm」就等于没装。
- 检查项目根目录（即
project.config.json中miniprogramRoot指向的路径）下是否有package.json；没有就先运行npm init -y - 确保依赖写在
dependencies字段里，devDependencies在旧版开发者工具中可能被跳过 - 构建后检查是否生成了
miniprogram_npm/xxx目录；没生成说明该包用了fs、crypto、window等小程序禁用 API - 常见踩坑包：
axios@1.x（依赖fetch）、uuid@9+（依赖crypto）、moment（体积大且含大量 polyfill）——应换为uni.request+dayjs+uuid@8.3.2
构建 npm 的正确操作路径
不是 HBuilderX 点运行就能触发，也不是命令行 npm run build:mp-weixin 自动包含这步——它必须由微信开发者工具手动执行。
- 打开微信开发者工具，确保项目已加载（右上角显示项目路径）
- 点击顶部菜单栏「工具」→「构建 npm」
- 勾选「使用 npm 模块」，点击「确定」
- 等待进度条结束，控制台输出「构建完成」，再检查
miniprogram_npm/是否存在对应包目录 - 如果用 HBuilderX 开发，务必先在微信开发者工具里完成构建，再点「运行到小程序模拟器」，否则 HBuilderX 不会同步
miniprogram_npm
平台判断与 API 替换是跨端关键
同一个 import 语句，在 H5 能跑，小程序会挂，App 可能又行——因为运行时环境差异极大。不能靠“试试看”，得主动隔离。
- 用
process.env.UNI_PLATFORM做条件分支，比如：if (process.env.UNI_PLATFORM === 'mp-weixin') {<br> uni.request({...})<br>} else {<br> fetch(...)<br>} - 避免在组件
data或created钩子中直接调用浏览器专属 API，提前在onLoad或onShow里做平台校验 - 第三方库若含副作用（如自动执行 DOM 操作），需用
uni.getSystemInfoSync()判断环境后再动态import() - 像
@dcloudio/uni-ui这类专为 uni-app 设计的包可直接用；但@vant/weapp是小程序专用，只能用于mp-weixin平台，不能写进公共逻辑
最常被忽略的一点：构建 npm 不是一劳永逸。只要改了 package.json（增删依赖、升级版本），就必须重新点一次「构建 npm」，否则 miniprogram_npm 不会更新，新代码依然引用旧文件。
