做前端或者跑Node脚本，谁都逃不掉和npm install打交道。但说实话，很多人对它的认知停留在“装依赖”这一步，遇到--save-dev、--save-exact、--legacy-peer-deps这些参数就靠猜，装坏了就删node_modules重来。我在团队里看过太多次这种“能用就行”的用法，最后变成本地好好的、同事一拉代码就报错，或者生产环境装出了完全不同的依赖树。这篇文章就把npm install的常用参数一个个掰开揉碎讲清楚，重点放在“什么场景用什么参数”以及“为什么这么用”。如果你已经会用基础命令但总在一些坑里打转，这篇内容应该能帮上大忙。
1. install 的基础逻辑与参数全景
很多报错和困惑都源于没搞清楚npm install背后到底做了什么。它不是一个“把 package.json 里的包全装一遍”的简单动作，而是一套依赖解析、版本匹配、锁文件更新的完整流程。只有先把这条主线理清，后面看参数才不会乱。
1.1 install 到底在干什么
运行npm install时，npm 会先看当前目录下有没有package-lock.json。有锁文件，npm 会优先按照锁文件里记录的精确版本、下载地址和依赖关系来安装，而不是重新解析一遍 package.json 里那些^1.2.3之类的范围。这样做的目的很明确：保证每个人装的依赖树一致，保证同一个项目在本地、CI、服务器上拿到的内容一样。没有锁文件，npm 就会读取 package.json，根据每个依赖的 semver 范围解析出当前最新的满足版本，然后生成锁文件并写入node_modules。
所以npm install的参数大体上是在回答四类问题：装到什么位置、要不要写入清单、版本范围怎么保存、遇到冲突和网络问题怎么办。比如--save-dev决定写入哪个清单字段，--global决定装到全局还是当前项目，--save-exact决定版本号写不写^前缀。如果把问题归到这四类，参数表就不难记了。
还有一个容易混淆的点：npm install默认会执行依赖生命周期脚本（比如某些包的install、postinstall脚本），所以安装的时候卡在某个奇怪的地方，往往不是下载慢，而是某个依赖在跑脚本。这跟参数的关系不大，但遇到问题时要有这个意识。
1.2 参数全景图与记忆方法
不需要把 npm 官方文档里二十几个冷门参数全背下来，工作中高频用到的基本就下面这些。我按功能分了个组：
| 分组 | 常用参数 | 一句话作用 |
|---|---|---|
| 保存位置 | --save/-S、--save-dev/-D、--global/-g、--no-save | 控制依赖记录到哪、装到哪 |
| 版本策略 | --save-exact/-E、--save-prefix、--save-bundle | 控制写入 package.json 的版本号格式 |
| 依赖处理 | --omit=dev、--legacy-peer-deps、--force、--dry-run | 控制依赖类型、绕过规则、模拟操作 |
| 网络与缓存 | --registry、--offline、--prefer-offline、--cache | 控制从哪里取包、用不用缓存 |
| 辅助功能 | --no-audit、--no-fund、--loglevel | 控制安装过程中的附加行为 |
记忆方法就一条：先问自己“我要装到哪、要不要记录、怎么记、遇到冲突怎么办”，然后再去找对应参数。比如临时试一个包，就大概率用--no-save；要固定 CLI 工具版本，就用--save-exact；项目里有 peer 依赖冲突还不想升级，再考虑--legacy-peer-deps。
2. 依赖保存类参数与场景拆解
这一类参数直接决定package.json会变成什么样，也最容易踩坑。很多“为什么我 package.json 里没有这个依赖”的问题，基本都出在这。
2.1 --save / -S 与 dependencies 的适用场景
--save是 npm 5 之后的默认行为，也就是说你直接执行npm install lodash，它也会自动写入dependencies。为什么要单独讲这个已经默认的参数？因为两种场景下仍然需要显式关注。
第一种，运行时代码必须用到的依赖，比如express、axios、react。它们会被打包到线上产物里，或者作为服务端运行时的直接依赖。这类包必须放在dependencies，因为部署环境执行npm install --omit=dev之后，只有dependencies里的包还在。如果你不小心把运行时依赖写进了devDependencies，生产环境就会直接Cannot find module。
第二种，项目里某些包是从本地文件安装或者从私有仓库安装的，直接安装时 npm 可能识别不出正确的保存字段。我遇到过装私有包时默认写进了optionalDependencies，导致可以被跳过的情况。这时候显式加--save更稳妥，能明确指定写入位置。
实操建议：在已有的老项目里新增运行时依赖，我会习惯性在命令末尾加-S，虽然它是默认行为，但这样做的价值在于当 npm 版本或项目配置发生变化时，这个语义依然是明确的。再看一眼 package.json diff 确认写对了位置，这比自己背规则靠谱。
2.2 --save-dev / -D 与 devDependencies 的边界
开发依赖的核心判断标准是：这个包在生产环境“真正运行代码”时是否需要。测试框架、打包工具、代码检查器、TypeScript 编译器，这些只在开发和构建阶段出现，等构建出产物后就不再参与运行了，所以应该放devDependencies。
但边界很容易模糊。举一个我实际处理过的例子：某个内部脚手架，同时提供了开发命令和线上运行命令，其中部分工具函数在线上也会被调用。团队里一位同事图省事把它安装到 devDependencies，结果 CI 打包时用了--omit=dev，线上任务直接找不到模块。后来我们把这类工具拆成了两个包，运行时需要的部分放 dependencies。
另一个边界是 type 定义包，比如@types/node。如果项目发布的是 JavaScript 库，类型定义只在别人使用编辑器提示或者tsc检查时需要，但对你的库来说，它只是开发期帮助测试代码类型，放 dev 合理。如果发布的是带类型声明的包，且使用方需要这些类型，那@types/*应该作为 dependencies 或者 peerDependencies 出现。判断错了，要么包变大，要么使用方缺类型。
还要记住一个反向场景：npm install --save-dev在安装rollup、esbuild这类带二进制文件的包时，--omit=dev之后不会安装它们，但这恰恰是我们想要的，因为构建在之前已经完成，线上只需要产物。
2.3 --global / -g 全局安装的利弊
npm install -g pnpm、npm install -g typescript，这类命令装机率很高。全局安装解决的问题只有一个：在任意目录的命令行里直接使用某个 CLI 工具。所以判断标准非常明确：这个工具是不是你要在不同的项目里反复调用？是，就全局装；只是某个项目里用到，优先作为 devDependencies 安装，再用npx pnpm或./node_modules/.bin/方式调用。
全局装的坏处主要在三块。第一是版本污染：不同项目可能需要不同的全局版本，全局只有一个版本时必然有人踩坑。第二是升级麻烦：全局包更新后可能影响所有项目。第三是权限问题：用系统 Node 安装全局包经常遇到 EACCES，不少人直接 sudo，导致后续所有全局目录文件权限错乱。
我的建议是优先用 Node 版本管理工具来隔离环境和全局包，让每个 Node 版本拥有自己独立的全局目录。需要切换版本时，全局包也跟着切换，不会互相污染。如果只是临时用某个 CLI，直接npx package-name最省事，用完不残留。
2.4 --no-save / 临时安装与 --package-lock-only
--no-save的场景很典型：你遇到一个问题，想临时装个包验证一下某个 API 或者看下源码。正常安装会污染package.json和锁文件，不装又没法验证。这时候npm install some-pkg --no-save就能把它装进node_modules，但不会写入package.json。等验证完，删掉 node_modules 里的对应目录即可。
但注意一个细节：--no-save并不会阻止package-lock文件发生变化。在某些 npm 版本下，即使 package.json 没变，锁文件也可能被更新。如果团队严格要求锁文件版本稳定，执行临时安装前记得先保存好原有锁文件，或者安装完成后检查并回滚。
--package-lock-only则是另一个很实用的参数。它只更新锁文件，不下载和安装任何包到 node_modules。听起来好像没什么用，但实际有两个高频场景：一是团队决定统一调整依赖版本范围时，可以先手动改 package.json，再执行npm install --package-lock-only生成新的锁文件，提交后其他人通过npm ci即可。二是安全团队扫描出某个依赖存在漏洞，你只需要在 CI 环境中重新锁定修复版本，又不想把本地 node_modules 弄得乱七八糟，用这个参数就能一步到位。
3. 版本控制与兼容性参数
安装依赖时，npm 默认会在package.json里写入带^的语义化版本范围，比如^1.2.3表示“允许 1.x.x 范围内的小版本升级”。这种设计本意是灵活，但在实际项目中经常翻车：某天执行npm update，某个依赖的 minor 版本引入了破坏性变更，应用就崩了。所以版本控制类参数解决的核心问题是：你到底想让依赖多“自由”。
3.1 --save-exact / -E 与依赖锁定
--save-exact会去掉版本号前面的^，写成1.2.3。这样 npm 在安装时只认这个确切版本，不会自动向上兼容。使用这个参数的典型场景是命令行工具和配套的生态工具：如果团队统一使用typescript@5.2.2，但 package.json 里写^5.2.2，其他人拉代码后 lockfile 缺失时可能装出5.20.0，正好某个 API 变了，构建就挂了。把这类“与工作流强相关”的工具用-E固定，能省掉很多折腾。
不过现在有package-lock.json存在，是不是--save-exact就没用了？不是。锁文件锁定的是已经生成的解析结果，但 package.json 的语义化范围决定了未来npm update或重新解析时的升级空间。对于应用项目，我一般保留默认的^，靠锁文件保证可复现；但对于依赖库本身，特别是第三方依赖需要兼容多个版本时，--save-exact能减少发布版本的不确定性。个人经验是：运行时的核心依赖（比如数据库驱动、消息队列客户端）建议用-E，开发工具类依赖可以放宽。
3.2 --save-prefix 定制版本范围
--save-prefix可以自定义保存依赖时写入的版本范围前缀。默认是^，你可以改成~，这样版本范围变成~1.2.3，表示只允许补丁版本升级，不允许 minor 和 major 升级。这个参数的使用频率不高，但很适合一类特殊依赖：某个库的 minor 版本经常发生破坏性变更，团队暂时没法跟上，只能锁定在同一个 minor 系列里。
记得一次项目中用了一个监控 SDK，它的1.3.0版本改了上报接口的路径参数，升级到1.4.0后现有代码直接发不出数据。当时没有深究 semver 规范，SDK 作者也把兼容性变更发在 minor 版本里。后来我们在.npmrc里配置了save-prefix="~"，之后安装的依赖都锁定在同一 minor。当然这同时也意味着新功能自动更新受限，所以这个配置一般只对个别包有意义，不建议全局长时间启用。
3.3 --force / --legacy-peer-deps 处理冲突
这两个参数经常被当成“万能解药”混在一起用，但它们处理的冲突不太一样。--force是一个大杂烩开关，它让 npm 强制执行某些操作，例如重新获取本地缓存外的所有包、忽略一些一致性检查，甚至能覆盖依赖目录的完整性校验。遇到缓存损坏、node_modules 和锁文件对不上这类问题，--force有一定效果，但副作用是可能把很多原本正常的依赖顺序打乱。
--legacy-peer-deps则专门针对 peer 依赖冲突。npm 7 开始，如果安装的包与已有的 peerDependencies 声明不一致，会直接报ERESOLVE错误并拒绝安装。比如某个 UI 组件库声明的 peer 依赖是 React 17，而你的项目里是 React 18，install 就无法继续进行。这时--legacy-peer-deps会让 npm 回到 npm 6 时代的行为：不自动安装 peer 依赖，也不严格校验版本，只警告一声就继续。
但必须提醒：--legacy-peer-deps是绕过问题，不是解决问题。我用过很多次，最稳妥的做法是先用npm view <包名> peerDependencies查清楚它到底需要什么版本，然后升级或降级到兼容版本。如果确实没法兼容，再在项目级.npmrc里加legacy-peer-deps=true，同时要在 README 里注明原因，避免后人踩坑。生产环境更不要轻易使用--force去“修”peer依赖冲突，那可能装出一个运行期才会炸的依赖树。
3.4 --omit=dev / --production 环境隔离
生产环境安装依赖要求必须跳过开发依赖，避免把测试用例、打包工具等装到服务器上。npm install --omit=dev可以做到这一点，它的历史写法是npm install --production，或者通过设置NODE_ENV=production触发。不过我推荐显式使用--omit=dev，因为--production会受环境变量影响，跨平台时NODE_ENV=production npm install在 Windows 上需要cross-env，不设置还容易失效。显式参数最直白。
这个参数的实际收益挺明显。一个包含eslint、jest、vite等一堆开发工具的项目，跳过 devDependencies 后，依赖数量往往能减少一半以上，安装时间几乎缩短到原来的三分之一，线上容器体积也更小。另外，--omit=optional也可以按需跳过可选依赖，那些带原生二进制模块的包会在这里出问题，跳过可以避免在特定 CPU 架构上安装失败。
这里有个容易犯的错：项目里误把运行时依赖装到 devDependencies，然后--omit=dev安装，线上就会报模块找不到。所以每次切换生产安装模式之前，最好用npm ls --omit=dev验证一次线上可见的依赖树，确认核心依赖都在里面。
4. 网络与缓存场景的参数实操
npm 安装慢、失败、卡住，大多跟网络和缓存有关。这些参数不改变依赖保存方式，但对安装过程的稳定性和速度影响非常大。很多团队把npm install玩得溜，就是把这类参数组合用对了。
4.1 私有镜像与 registry 参数
--registry参数可以临时指定某个 npm 镜像源或私有仓库地址。使用场景非常明确：公司内部发布私有包，或者在国内访问官方源太慢需要换用镜像。基本用法是：
npm install --registry=https://registry.example.com实际操作中，我很少在每次命令后面都带着一长串 registry。更常规的做法是写在项目根目录的.npmrc文件里，比如：
registry=https://registry.npmmirror.com这样整个团队只要拉代码，就会带上这份配置，不需要每个人都手动设置。但要注意.npmrc里的配置会被用户的全局配置覆盖吗？优先级是命令行参数 > 项目级.npmrc> 用户级.npmrc> 全局.npmrc。如果用户本地有自己的 registry 配置，可能覆盖项目级，从而安装不到私有包。排查这类问题，可以先执行npm config get registry看看当前生效的仓库地址。
还有一个坑：私有仓库的 access token 不要把明文写到项目里。可以设置//registry.example.com/:_authToken=${NPM_TOKEN}，然后在 CI 或本地通过环境变量注入 token。这样.npmrc即使被提交也不会泄露敏感信息。
4.2 离线安装与 cache 参数
离线安装对网络受限的内网环境访问量很大。npm 支持三种模式：
| 参数 | 行为 |
|---|---|
--offline | 完全不访问网络，只从本地缓存中解析包。缓存没有就直接失败 |
--prefer-offline | 优先使用本地缓存，缓存不存在或过期后才请求网络 |
--prefer-online | 优先请求网络，网络不可用时回退到缓存 |
实际使用中，--offline适合已经提前把所有依赖都缓存一遍的环境。比如某内网开发机，可以先用一台能联网的机器执行npm install，执行完后本地缓存里就有了依赖包。之后把整个用户目录下的 npm 缓存目录打包到内网机器，再用--offline --cache 指定目录安装，完全不需要网络。
--prefer-offline则更适合 CI 场景：每次构建都希望尽量快，本地缓存有就用，没有再去拉。配上持久化的缓存目录，比如 CI 的$NPM_CACHE_FOLDER，能把重复安装的时间大幅压下来。
还要注意，npm 的缓存设计不是简单的“缓存一个 tar 包”，它是一套内容寻址的存储，分布在_cacache目录下。所以不要手动去 cache 目录里删某个文件名思，要用命令管理。查看缓存路径可以执行npm config get cache。
4.3 --no-audit / --no-fund 提升效率
这两个参数被很多人忽略，但它们对安装速度的影响比想象中明显。npm install默认会做安全审计（audit），每次都会请求安全漏洞数据库；还会检查包的赞助链接并打印一串基金信息。在公司复杂网络环境里，audit 请求经常超时，导致 install 最后一步卡很久。
使用方式：
npm install --no-audit --no-fund在 CI 脚本和 Docker 构建中，我会默认加上这两个参数。本地开发需要安全提醒，可以不加。如果担心跳过 audit 会漏掉漏洞，可以在 CI 单独一个定时任务执行npm audit用于安全巡检，而不是每次 install 都全量审计。
辅助提速的参数还有--loglevel=error，只输出错误信息，防止 CI 日志被一堆 “added 500 packages” 刷屏。结合--no-audit --no-fund，安装过程的噪音会小很多，定位问题也更方便。
5. 常见问题与排查技巧实录
参数知道得再多，最终还是要在实际报错里生存。这一节我把自己踩过的一些坑和排查方法整理出来。问题不一定每个项目都会遇到，但遇到一个就能帮你省下半天时间。
5.1 Lockfile 冲突与合并
package-lock.json 特别容易在多人协作时产生冲突。场景很常见：A 同事在分支上加了lodash，B 同事在另一个分支上加axios，两个分支的锁文件都改了。等合并代码时，Git 会在 lock 文件里标记冲突，而且这个冲突往往不是一两行，是几十个依赖块的修改。
我之前见过有人直接删掉package-lock.json和node_modules，重新生成一份。这样能跑通，但会把锁文件里所有依赖版本“顺手”升级到当前范围内最新版，可能引入不必要的变更，甚至让线上和本地版本不一致。更可控的做法是：
- 先解决好
package.json里的冲突，让它在合并后保持你想要的依赖集合。 - 对于
package-lock.json，选择其中一个版本的完整文件（比如git checkout --ours或--theirs），不要手动拼接。 - 执行
npm install --package-lock-only，让 npm 根据最终 package.json 和选中的 lock 重新计算并生成一个合并后的锁文件。 - 运行
npm ci验证安装是否正常。
这样做的好处是，冲突被 npm 的解析机制处理，而不是靠人手工去猜。
5.2 权限错误与 EACCES
安装依赖时报EACCES: permission denied, mkdir '/usr/local/lib/node_modules'，这个几乎碰上过。常见原因是用了系统自带 Node，全局安装目录属于 root，普通用户没有写权限。网上很多方案直接给npm install -g加 sudo，但这种方式会留下隐患：全局目录里混着 root 创建的文件，之后普通用户执行 npm 会继续报权限错，而且项目本地 node_modules 也有可能被 sudo 创建。
如果用的是系统 Node，建议直接把 npm 的全局前缀指到用户目录：
mkdir -p ~/.npm-global npm config set prefix '~/.npm-global'然后把~/.npm-global/bin加到 PATH 里。如果打算长期做 Node 开发，更推荐直接换用 Node 版本管理工具，比如 nvm，这样每个版本都有独立且可写的全局目录，权限问题基本绝迹。
本地项目的 node_modules 报权限错，一般是之前用 root 身份跑过 npm install，导致 node_modules 里某些文件的所有者是 root。不要尝试 fine-grained 修复，直接删掉 node_modules 和 package-lock，换当前用户重新安装。注意如果项目里有未提交的本地补丁，先备份。
5.3 依赖版本不兼容导致安装失败
npm 7 以来，ERESOLVE是高频报错之一。现象是装一个包时，npm 检查 peerDependencies 发现冲突，直接拒绝继续。例如：
npm ERR! code ERESOLVE npm ERR! Could not resolve dependency: npm ERR! peer react@"^17.0.0" from xxx很多人的第一反应是npm install --legacy-peer-deps绕过，但这不是治本。我的排查习惯是：
- 看报错里提到的冲突包和版本。
- 执行
npm view <冲突包> peerDependencies --json，看它到底需要什么版本范围。 - 对比项目里已安装的版本，决定升级冲突源还是升级或降级对方。
- 如果是新引入的包导致的冲突，先去该包仓库看 issue，往往有版本兼容说明。
- 确实无法解决的，再在
.npmrc里加legacy-peer-deps=true，同时记录原因。
不要在生产环境装依赖时加--force硬闯，因为 peerDependencies 本身就是在提醒你“这两个包可能不能在一起用”。绕过去一时痛快，运行期接口不匹配才最难受。
5.4 缓存污染与清除
npm install偶尔会报Unexpected end of JSON input或者校验和失败，这种基本就是本地缓存污染了。我在内网环境遇见最多：下载到一半断网，缓存里残留了残缺数据，下次 install 即使重新下载也可能读到坏块。
处理方式分层次，不要一上来就npm cache clean --force。这个命令会把整个缓存清空，下次安装全部重下，耗时很长。更推荐先执行：
npm cache verify这个命令会验证缓存数据完整性，删除垃圾内容并报告缓存索引。如果 verify 之后问题还在，再针对具体包排查。实在不行再npm cache clean --force，或者直接删除npm config get cache指向的目录。删缓存不会影响 node_modules，但会失去离线安装的兜底。要是 CI 环境用了持久化缓存，清缓存时还要记得命中断缓存 key，不然也没用。
另外顺带提一句：如果 node_modules 本身状态异常，优先用npm ci而不是npm install。npm ci会严格按照锁文件安装，并自动清空 node_modules 后重新安装，适合 CI 也适合本地“彻底重装”的场景。但注意npm ci要求存在 package-lock.json 或 npm-shrinkwrap.json，否则会报错。
6. 一些实操心得与取舍建议
文章讲到这里，参数本身其实不难，难的是你愿不愿意每次多想一想“这个命令会改哪些文件，会不会影响别人”。我在实际带项目时，会给安装命令定几个默认的“安全姿势”：本地开发偶尔装新包，我会用默认保存行为，但装完立刻看一眼 package.json 的 diff；改动依赖后必装一次npm ci确认锁文件和 node_modules 能对上；CI 脚本里一律用npm ci --no-audit --no-fund --prefer-offline；生产环境构建再用npm install --omit=dev，让开发依赖彻底消失在生产目录里。
还有一个容易被忽略的点：给团队统一维护一份.npmrc，把registry、cache、legacy-peer-deps这类“环境差异化配置”固定下来。别让每个人靠记忆里上次的命令参数去装依赖，那才是混乱的根源。参数用得清楚，依赖树就干净，线上问题也少一半。
