npm 命令速查表 - Node.js 包管理常用命令大全
Node 项目可不可复现，很大程度上取决于你怎么写依赖命令。本表串起整个生命周期：init/脚手架、安装更新卸载、版本范围与 package-lock、npm scripts 与 npx、npm ls/audit/outdated 排查依赖健康、发布，以及 config/cache 的调整。相比简单的命令列表，还特别标出 lockfile 与 audit 里容易咬人的细节。CI 在依赖解析上失败、或某个包装不到预期版本时最有用。读完能带着意图操作依赖并定位安装问题。
典型使用场景
面向用 npm 管理 Node.js 项目的开发者。本表把易混的四处讲透：npm install 与 npm ci 的区别（前者会改 lock、CI 必须用后者）、npm run 与 npm start/npm test 的简写关系、-D 与 -g 的作用范围、以及 npx 免全局安装的用法。另外 npm ls --depth=0 与 npm why 是排查「幽灵依赖」与版本冲突的正规路径，比反复删 node_modules 更有效。
项目初始化 4
npm init -ynpm initnpm init <initializer> [args]npm create <initializer>@latest安装与卸载 7
npm installnpm install <pkg>npm install -D <pkg>npm install -g <pkg>npm install <pkg> --save-exactnpm uninstall <pkg>npm uninstall -g <pkg>版本管理 6
npm install <pkg>@1.2.3npm install <pkg>@latestnpm install <pkg>@^1.0.0npm update [pkg]npm outdatednpm dedupe脚本与运行 6
npm run <script>npm startnpm testnpm runnpx <command> [args]npm run <script> -- --port 8080依赖查看 6
npm lsnpm ls --depth=0npm ls <pkg>npm why <pkg>npm auditnpm audit fix发布管理 5
npm version <patch|minor|major>npm publishnpm publish --tag betanpm deprecate <pkg>@<ver> "原因"npm owner add <user> [<pkg>]配置与缓存 7
npm config get registrynpm config set registry https://registry.npmmirror.comnpm config set <key> <value>npm config listnpm cache clean --forcenpm cache verifynpm ci参数矩阵
| 参数 | 作用 | 示例 |
|---|---|---|
init -y | 用默认值快速生成 package.json | npm init -y |
init <initializer> | 脚手架创建项目 | npm init vite |
install <pkg> | 装入 dependencies | npm install express |
-D | 装入 devDependencies（构建期依赖） | npm install -D typescript |
-g | 全局安装 | npm install -g pnpm |
--save-exact / -E | 锁定精确版本，不带 ^ | npm install pkg --save-exact |
pkg@1.2.3 / @latest | 指定版本 / 最新版 | npm install pkg@1.2.3 |
update | 更新到符合 semver 的最新版 | npm update |
dedupe | 去重依赖树减少重复安装 | npm dedupe |
run <script> | 执行 scripts 中的脚本 | npm run build |
npx | 临时执行包，无需全局安装 | npx create-react-app my-app |
run <s> -- --arg | 用 -- 透传参数给脚本 | npm run dev -- --port 8080 |
ls --depth=0 | 只看顶层直接依赖 | npm ls --depth=0 |
why <pkg> | 反查依赖是被谁引入的 | npm why lodash |
ci | 按 lock 干净安装，CI 推荐 | npm ci |
config set registry | 切换镜像源 | npm config set registry https://registry.npmmirror.com |
易错点与避坑指南
现象本地跑得好好的，CI 上安装依赖时报版本不一致。
原因package-lock.json 未提交或已过期，CI 自行解析出了不同版本。
处置提交 package-lock.json，CI 改用 npm ci（严格按 lock 安装且会先清空 node_modules）。
现象代码里 import 某个包本地正常，部署后报 module not found。
原因该包被装成了 devDependencies，npm ci --omit=dev 或生产安装时被跳过。
处置运行时真正需要的包必须写在 dependencies；构建期工具才放 devDependencies。
现象npm audit fix 后大量依赖主版本跳变，代码大面积报错。
原因audit fix 可能引入破坏性更新，尤其是跨主版本。
处置先在分支试跑并跑测试；生产环境慎用 --force，逐个手动升级受影响的包。
现象npm install 卡在下载或报网络错误。
原因默认 registry 在境外，网络不通。
处置npm config set registry https://registry.npmmirror.com 切换镜像；企业环境按内网源配置。
现象同一个包在依赖树里出现了多份不同版本。
原因各依赖的 semver 范围不兼容，npm 各装一份。
处置npm ls <pkg> 看有几份；npm dedupe 去重，或用 npm overrides 强制统一版本。
现象npm run 传参后脚本收到的参数不对。
原因缺少 -- 分隔符，参数被 npm 自身解析。
处置写成 npm run dev -- --port 8080。
现象全局安装的包在项目里仍然 command not found。
原因npm 全局 bin 目录不在 PATH 中。
处置npm bin -g 查看路径并加入 PATH；更好的做法是用 npx 避免全局安装。
现象npm cache 目录越来越大，构建变慢。
原因缓存长期未清理。
处置npm cache verify 检查并清理；CI 中可用 --prefer-offline 复用缓存加速。
排障路径
1CI 环境用 lock 文件干净安装
npm ci严格按 package-lock.json 安装且先删 node_modules，比 install 更可靠更快。
2确认某包是否装上及其版本
npm ls <pkg>输出里出现多份版本即说明依赖树有冲突。
3反查依赖是被谁引入的
npm why <pkg>决定能否移除该依赖，或需要加到 package.json 里显式声明。
4排查版本冲突
npm ls --depth=0只看顶层直接依赖，肉眼更快；确认无误后再看完整树。
5临时运行包而不全局安装
npx create-react-app my-app避免污染全局环境；CI 中也常用 npx 执行一次性任务。
命令示例
追踪某个依赖是谁引入的
npm why lodash
npm ls lodash --depth=0npm why 反向追溯，npm ls 看实际安装的版本树。排查版本冲突先 npm ls 定位重复安装，再 npm why 判断能否移除。
输出
user@1.0.0 /home/tom/app └── lodash@4.17.21 └── lodash@4.17.21
CI 里用 ci 保证可复现
npm ci
# 报错示例：package.json 与 lock 不一致时 ci 直接失败ci 严格按 lock 安装且不更新版本，与 install 行为不同。lock 与 package.json 不一致时它会直接失败——这正是想要的：暴露忘记提交 lock 的问题。
输出
npm warn old lockfile npm error `npm ci` can only install packages when your package.json and package-lock.json are in sync
锁定精确版本
npm install <pkg> --save-exact
# package.json 里写 "pkg": "1.2.3" 而非 "^1.2.3"-E/--save-exact 去掉 ^ 前缀。核心依赖建议锁精确版本，次要依赖用 ^ 兼顾安全更新与可复现。
常见坑与注意事项
- package-lock.json 必须提交到 Git；不提交则 CI 每次可能装到不同版本，构建不再可复现。
- npm install 会更新 lock 并可能升级依赖，CI 中应改用 npm ci 保证严格按 lock 安装。
- ^ 允许次版本升级、~ 只允许补丁升级，语义不同；核心依赖建议用 --save-exact 锁死。
- npx 会临时下载并执行远程包，对不可信的包名等同于执行陌生脚本，先确认包来源。
- 全局安装的 CLI 与项目内版本可能不一致，CI 中应优先用 npx 或 npm run 调用项目内版本。
提示
- npm install 不带参数会安装 package.json 中的所有依赖。
- package-lock.json 锁定依赖版本，应该提交到版本控制。
- npx 可以临时运行包而不全局安装，如 npx create-react-app my-app。
- npm ci 比 npm install 更快更可靠，适合 CI/CD 环境，要求 lock 文件存在。
- npm config set registry https://registry.npmmirror.com 切换国内镜像加速下载。
- npm audit fix --force 可能引入破坏性更新，生产环境慎用。
常见问题
npm ls 和 npm why 有什么区别？
npm ls 展示整棵依赖树，npm ls --depth=0 只看顶层直接依赖，肉眼更快；npm why <pkg> 反向追溯某个包是被谁的依赖带进来的，用于判断删掉某个依赖会有什么影响。排查版本冲突先看 npm ls，确认某个包为何存在用 npm why。
package-lock.json 应该提交到 Git 吗？
应该提交。它锁定了整棵依赖树的确切版本，是构建可复现的前提。提交后 CI 用 npm ci 而非 npm install——ci 会严格按 lock 文件安装，不更新版本，在 lock 与 package.json 不一致时直接报错，这正好能暴露出忘记更新 lock 的情况。
^ 和 ~ 在版本号里分别表示什么？
^ 是插入号，允许次版本号与补丁号升级但不动主版本号，^1.2.3 接受 1.x.x 而不接受 2.0.0；~ 是波浪号，只允许补丁号升级，~1.2.3 接受 1.2.x 但不接受 1.3.0。npm install --save-exact 会写成不带前缀的精确版本，适合需要严格锁定的库。
依赖有安全漏洞怎么查？
npm audit 会扫描依赖树并报告已知漏洞，配合 npm audit fix 可以自动升级到修复版本。排查某个包为什么被装进来用 npm why <pkg>，如果只是某个功能顺带引入的，可以在直接依赖里用 overrides 固定它的版本，或考虑改用更轻的替代方案。锁文件里有漏洞时，先 npm audit fix 再重新跑测试确认没有破坏。
npx 什么时候比全局安装更合适？
当工具只偶尔用一次时。npx <command> 会临时执行本地或远程包而无需全局安装，既省去安装与卸载的麻烦，也不会污染全局环境。像 npm run 之外的调试工具、一次性脚本、或者想在 CI 里验证某个包的 CLI，都适合用 npx。需要频繁调用且要求启动速度的，才值得全局安装。
由 巧匠 维护
公开更新于 2026年7月21日，内容持续校对官方文档。