uni-app 报 Module not found 多因依赖装错位置（须在项目根目录）、工具链不兼容（推荐 npm）、误用 Node.js 原生模块（如 fs），或 IDE 缓存未更新（需删 .hxcache 并重新编译）。
npm install 后 uni-app 还报 Module not found
多数情况不是没装，而是装错了位置或装错了范围。uni-app 项目依赖必须装在项目根目录（即含 package.json 和 pages.json 的那一层），不能在子文件夹里执行 npm install。
常见错误现象：npm install axios 执行完，运行 uni.previewImage 没问题，但 import axios from 'axios' 报错；或者 HBuilderX 提示“找不到模块”，而命令行 node -e "require('axios')" 却能成功——说明模块装到了全局或别的项目里。
- 确认当前终端路径是否为项目根目录：检查是否有
package.json，且里面包含"name"字段和"dependencies"或"devDependencies" - 不要用
sudo npm install（尤其 macOS/Linux），它可能把包装进系统级 node_modules，uni-app 构建时不会读取 - 如果用 pnpm/yarn，请统一工具链：HBuilderX 内置的编译器只认
node_modules，不识别.pnpm或yarn.lock的硬链接结构，建议优先用 npm - 装完后删掉
node_modules和package-lock.json，再重装一次，避免缓存污染
uni-app 能不能直接用 Node.js 原生模块（如 fs、path）
不能。uni-app 编译目标是小程序、H5、App，这些环境没有 Node.js runtime，fs、os、child_process 等模块在运行时会直接报 ReferenceError: fs is not defined 或 Can't resolve 'fs'。
使用场景很明确：只有服务端（如云函数）或本地开发脚本（非 uni-app 源码）才能用这些模块。前端代码里写 require('fs') 或 import { writeFile } from 'fs/promises' 必炸。
- 替代方案：H5 可用
Blob+URL.createObjectURL；小程序用uni.downloadFile+uni.saveFile；App 端可调用原生插件封装文件操作 - 构建时被 webpack 拦截的提示如
Critical dependency: the request of a dependency is an expression，往往也是误引入了服务端模块 - 注意某些包（如
moment）有浏览器兼容版，但date-fns更轻量、无副作用，推荐优先选后者
npm install 安装的包在不同平台表现不一致
根本原因是 uni-app 对各端的 API 抽象层不同，而 npm 包内部可能做了环境判断（比如检测 typeof wx !== 'undefined'），导致 H5 正常、微信小程序白屏、App 端报错。
典型例子：lodash 没问题，但 jszip 在小程序里解压失败；crypto-js 可用，node-forge 却提示 Cannot find module 'crypto'——因为后者试图加载 Node 原生 crypto，而 uni-app 小程序环境只提供 uni.getSystemInfo 这类 API。
- 查包是否标注了
"browser"字段（看其package.json），这是 webpack 浏览器环境入口标识 - 优先选带
esm输出、无__dirname/require.resolve的包，减少构建期解析失败 - 用
console.log(process.env.UNI_PLATFORM)在代码里确认当前平台，再做条件导入，比如：const utils = process.env.UNI_PLATFORM === 'h5' ? require('./h5-utils') : require('./mp-utils') - 真机调试比模拟器更早暴露兼容问题，iOS App 端对
eval、with、动态import()更敏感
装了包但 HBuilderX 不识别、不提示、不编译进包
本质是 IDE 缓存和构建系统未联动。HBuilderX 不完全依赖 node_modules 实时扫描，它有自己的模块索引机制，尤其在启用了 “自定义构建” 或 “vue-cli 项目” 模式时容易脱节。
错误现象包括：代码里写了 import { throttle } from 'lodash'，但 Ctrl+点击跳不到定义；运行时报 Cannot find module 'lodash'；甚至热更新后新包仍不生效。
- 关闭 HBuilderX，删掉项目根目录下的
.hxcache文件夹（隐藏目录），再重启 IDE - 右键项目 → “重新编译项目”，而不是只点“运行”——前者会清空临时构建产物并重走依赖分析
- 检查
vue.config.js是否配置了configureWebpack.resolve.alias，错误 alias 会覆盖真实模块路径 - 如果用了
uni_modules，注意它的依赖是独立管理的，需在对应模块目录下单独npm install，主项目不会自动继承
最麻烦的情况是包本身用了 ESM 语法但没提供 CJS 入口，uni-app 的 webpack 4 默认不处理顶层 export。这时候得手动配 transpileDependencies，或者换用已兼容的版本——这事没法绕，得看包作者有没有维护意愿。
