每个开发者都应该掌握的 npm 核心命令

你可能每天都在使用 npm install 和 npm run dev,已经习以为常。但 npm CLI 实际上拥有更强大的工具集,可以为你节省大量时间——无论是调试混乱的依赖树、审计安全漏洞,还是运行一次性脚本。本指南涵盖了每位开发者日常实践中应该掌握的核心 npm 命令和现代工作流模式。

安装和管理依赖

npm 依赖管理的核心工具是 npm install。不带参数运行时,它会将本地 node_modules 与 package-lock.json 同步。添加包名可以安装新的依赖:

npm install react            # runtime dependency
npm install vite --save-dev  # dev-only dependency

要安全地移除包并同时清理 package.json:

npm uninstall lodash

检查项目中哪些包已过期:

npm outdated

这会给你一个清晰的表格,显示当前版本、期望版本和最新版本——在决定更新什么以及何时更新时非常有用。

运行脚本和传递参数

不带任何参数运行 npm run 会列出 package.json 中定义的所有脚本。当你刚接触一个不熟悉的项目时很方便。

当需要向底层脚本传递参数时,使用 -- 来分隔:

npm run build -- --watch --mode=development

-- 之后的所有内容都会直接转发给脚本,这样你就可以调整行为而无需修改 package.json。

检查依赖树

开发者在调试依赖问题时应该掌握的两个命令是 npm ls 和 npm explain(也可以用别名 npm why)。

npm ls 会渲染完整的依赖树。传入包名可以过滤:

npm ls ms

npm explain 会告诉你某个特定包为什么被安装——是哪个直接依赖引入了它:

npm explain ms@0.7.1

对于更高级的过滤,npm query 允许你使用类似 CSS 选择器的 DSL 语法搜索依赖。例如,查找所有定义了 postinstall 脚本的包(这是一个有用的安全检查):

npm query ":attr(scripts, [postinstall])"

无需安装即可运行包

npm exec 使用项目的本地依赖运行包的二进制文件,如果包尚未安装,则临时下载。在现代 npm 版本中,npx 命令在底层委托给 npm exec。

npm exec -- create-react-app my-app

它首先查找项目本地的 node_modules,使行为比使用全局安装更可预测。

安全相关的 npm 命令

npm audit 会根据已知漏洞数据库扫描你的依赖树,并打印按严重程度排序的报告:

npm audit
npm audit fix          # 自动修复安全更新
npm audit fix --force  # 应用破坏性修复(之后需彻底测试)

为了供应链透明度,npm sbom 会生成软件物料清单(Software Bill of Materials)——以机器可读格式提供项目依赖的完整清单:

npm sbom > sbom.json

这个输出可以直接输入到 Snyk 等安全工具中进行更深入的漏洞扫描。

在升级前比较两个包版本之间实际发生的变化:

npm diff --diff=ms@2.1.2 --diff=ms@2.1.3

输出类似于 git diff,便于在变更进入项目之前发现意外修改。

锁定传递依赖

当漏洞存在于你无法直接控制的传递依赖中时,可以使用 package.json 中的 overrides 字段强制指定特定版本:

"overrides": {
  "node-ipc": "9.2.1"
}

注意 overrides 在 npm v8.3 及更高版本中支持。如果你使用 Yarn,等效功能是 resolutions。这是在不等待上游维护者的情况下维护安全依赖树的最实用方法之一。

总结

大多数开发者只触及了 npm 功能的表面。本文介绍的命令——从 npm explain 和 npm query 到 npm sbom 和 overrides——弥合了基础使用和真正高效工作流之间的差距。从与你当前痛点匹配的命令开始,逐步深入。

常见问题

npm exec 和 npx 有什么区别?

npm exec 是 npm v7 引入的内置命令,用于运行包的二进制文件,在现代 npm 版本中,npx 在底层委托给它。关键区别在于 npm exec 首先检查本地 node_modules,提供更可预测的行为。对于大多数日常任务,两者可以互换使用,但 npm exec 是未来推荐的方式。

如何修复 npm audit 发现的漏洞?

运行 npm audit fix 自动应用安全的、符合 semver 的更新。如果修复需要主版本升级,使用 npm audit fix --force,但之后要彻底测试应用程序,因为可能引入破坏性变更。对于你无法直接控制的传递依赖问题,使用 package.json 中的 overrides 字段锁定修补版本。

什么时候应该使用 package.json 中的 overrides 字段?

当传递依赖中存在漏洞或 bug,而引入它的直接依赖尚未发布修复版本时,使用 overrides。它强制 npm 解析该嵌套包的特定版本。此功能需要 npm v8.3 或更高版本。应用 override 后务必测试,因为强制指定版本可能导致兼容性问题。

如何确定某个特定包为什么在我的 node_modules 中?

运行 npm explain 后跟包名和版本,例如 npm explain ms@0.7.1。这会打印导致该包被安装的完整依赖链。你也可以使用简写 npm why。要查看整个依赖树的更广泛视图,使用 npm ls 并可选地添加包名过滤。