uni-app中npm install失败主因是装错目录、用错包管理器或误装Node原生模块;须在含pages.json的根目录用npm安装,禁用sudo、pnpm/yarn,微信小程序需配置packNpmManually并构建npm。

直接说结论:uni-app 项目里 npm install 失败,90% 不是网络或权限问题,而是装错了位置、用了不兼容的包管理器、或者误装了 Node.js 原生模块——这些错误在终端里看着像“找不到包”,实际根本没进对地方。
npm install 报错但 package.json 里明明写了依赖
常见现象:npm install axios 执行成功,但 uni-app 编译时仍报 Module not found: 'axios';或者 HBuilderX 提示“找不到模块”,而你在命令行里 node -e "require('axios')" 却能跑通。
- 根本原因:当前终端不在项目根目录(即含
package.json和pages.json的那一层),npm install把包装到了别处 - 确认方式:执行
pwd(macOS/Linux)或cd(Windows),看路径是否和pages.json所在目录一致 - 必须删掉错误位置生成的
node_modules,回到根目录再npm install - 不要用
sudo npm install(尤其 macOS/Linux),它可能把包写进系统级node_modules,uni-app 构建时压根不读
报 E404 或 “Not Found” 但包名没错
典型错误:npm ERR! 404 Not Found - GET https://registry.npmjs.org/@dcloudio%2funi-cli,或创建项目时报 Failed fetching remote preset dcloudio/uni-preset-vue。
- @dcloudio/uni-cli 和 @dcloudio/uni-preset-vue 在 npm 官方源已下架,淘宝、腾讯等镜像也同步移除了
- 不能靠换 registry 解决,必须改用官方推荐方式:用 HBuilderX 新建项目,或通过
npx degit dcloudio/uni-preset-vue#v3 my-project拉取模板(注意加#v3分支) - 全局安装
@dcloudio/uni-cli已无效,uni-app 当前构建逻辑完全走本地node_modules/.bin/uni,所以只装本地依赖即可
微信小程序构建 npm 报 “NPM packages not found”
错误信息明确指向微信开发者工具:NPM packages not found. Please confirm npm packages which need to build are belong to miniprogramRoot directory。
- uni-app 编译出的小程序代码默认在
dist/dev/mp-weixin,但微信开发者工具默认只认项目根目录下的miniprogramRoot(通常是dist/dev/mp-weixin) - 必须手动配置
project.config.json,在setting下加这两项:"packNpmManually": true"packNpmRelationList": [{"packageJsonPath":"./package.json","miniprogramNpmDistDir":"./dist/dev/mp-weixin"}] - 改完要重启微信开发者工具,再点“工具 → 构建 npm”,否则不生效
- 如果用了
threejs-miniprogram这类专为小程序封装的包,它内部有平台判断逻辑,不能直接import到 Vue 页面里,得在onLoad里动态require,否则编译期就报错
装完依赖,H5 能跑小程序白屏或报错
比如 jszip 在 H5 正常,小程序里解压失败;crypto-js 可用,node-forge 却报 Can't resolve 'crypto'。
- 根本原因:npm 包内部做了环境检测(如
typeof wx !== 'undefined'),但 uni-app 各端 runtime 差异大,有些包的“兼容判断”写得不严谨 - 优先选无副作用、按需引入的库:
date-fns替代moment,lodash-es替代lodash - 绝对不要在前端代码里 import
fs、path、os等 Node.js 原生模块,uni-app 编译目标没有 Node.js runtime,必炸 - 看到 webpack 提示
Critical dependency: the request of a dependency is an expression,基本就是误引了服务端模块,立刻检查 import 路径
最易被忽略的一点:uni-app 的依赖解析不走 pnpm 或 yarn 的硬链接结构,只认 node_modules 目录下的真实文件。哪怕你 pnpm install 成功了,HBuilderX 依然会报 Module not found —— 换回 npm 是唯一稳妥解法。











