LOADING...
仁戈头像首页关于技能作品博客联系
开发工具2026.09.2215 分钟

什么是 npm?一次把包管理和依赖讲清楚

npm 是 Node.js 生态的包管理器和公共软件仓库,它用 package.json 声明依赖、用 lock 文件锁定精确版本,并自动安装整棵依赖树。

什么是 npm?一次把包管理和依赖讲清楚

什么是 npm?

npm 是 Node.js 生态里的包管理器,全称是 Node Package Manager。它通过公共软件仓库和命令行工具,帮 JavaScript / Node.js 项目安装、升级、锁定和发布可复用的代码包。

npm 是 Node Package Manager,由 Node、Package 和 Manager 三部分组成

写 JavaScript 或 Node.js 项目时,不可能所有功能都从零实现。你需要用别人写好的代码,还要管理这些代码的版本,以及它们彼此之间的依赖。npm 就是为这件事准备的默认工具:安装 Node.js 时,通常也会一并得到 npm 命令行。

一句话总结:npm 不是单纯的下载器,而是 Node.js 生态里用来发现、安装、锁定和发布软件包的基础设施。

npm 解决了什么核心问题?

npm 解决的核心问题是:项目要复用别人的代码,同时把版本和依赖关系管起来,而不是每个功能都自己重写。

npm 连接“从零自己写”和“复用别人代码”,并负责版本管理与依赖管理

如果没有包管理器,常见结果是两头不讨好:

  • 自己从零写:日期计算、HTTP 请求、加密、构建工具都要重做,开发速度慢,也更容易出错。
  • 手动拷贝别人的代码:文件来源不清楚,版本对不上,升级时不知道该换哪些文件。

有了 npm,你可以从公共仓库安装已经发布的包,让版本号进入项目配置,再由工具自动处理后续依赖。它改变的是工作方式:从“到处找代码、手工粘贴”变成“声明需要什么,然后一条命令安装”。

因此,npm 的价值不在于让你少敲几行代码,而在于让复用、版本和依赖变成可自动执行的工程步骤。

npm 同时指哪三样东西?

npm 这三个字母经常同时指三样相关但不同的东西,很多人一开始会把它们混成一个概念。

npm 同时指公共代码仓库、命令行工具,以及日常口语里对前两者的统称

可以这样分开记:

  1. 公共代码仓库(registry):全球开发者把自己的包发布上去,其他人可以搜索和下载。这是包真正存放和分发的地方。
  2. 命令行工具(CLI):安装在电脑上的 npm 程序。你在终端里敲的 npm install,用的就是它。
  3. 日常说的 npm:口语里说“用 npm 装一个包”,通常同时指前面两样:仓库提供包,命令行负责下载和管理。

官方文档还会把 npmjs.com 网站单独算进去。网站用来浏览包、管理账号和组织权限;注册表是包的数据库;CLI 是开发者最常用的操作入口。对日常开发来说,先记住“仓库 + 命令行”就够用。

同一个名字,对应的是一套互相配合的系统,而不是一个孤立的下载按钮。

什么是包?

一个包(package)就是一份带说明文件、可以被安装和复用的代码,通常包含函数、组件或命令行工具。

包是可复用代码,常见形态包括函数、组件和工具,npm 仓库里已有超过两百万个包

更精确一点:npm 里的包必须有一份 package.json,用来描述名称、版本、入口文件和依赖。当前这个项目只要有 package.json,它本身也是一个包,哪怕你并不打算发布它。

一个常见例子是处理日期。你不必自己实现时区、格式化和日历计算,可以安装日期库,例如 dayjs:

npm init -y
npm install dayjs
const dayjs = require('dayjs')

console.log(dayjs().format('YYYY-MM-DD'))

包的形态并不只有函数库:

  • 函数或工具库:例如日期、校验、HTTP 客户端。
  • UI 组件:例如前端组件库里的按钮、表格、表单。
  • 命令行工具:例如创建项目的脚手架、代码检查和打包命令。

npm 官方把它称为世界上最大的软件注册表。仓库里现在有超过两百万个包。数量大意味着可复用代码多,也意味着筛选成本更高:同名功能可能有很多实现,维护状态、许可证和安全记录都需要判断,不能只看下载量。

为什么不能手动下载依赖,一定要有包管理器?

必须使用包管理器的核心原因,是依赖还有自己的依赖。你装的一个包,可能又依赖十个包,那十个包再各自依赖别的包。这棵树叫依赖树(dependency tree),靠手工维护几乎不可能。

你安装的一个包会展开成多层依赖树,手动维护几乎不可能,npm 会自动全部装好

以安装 Web 框架为例。你在项目里可能只写了一行直接依赖,真正装进 node_modules 的往往还有:

  • 直接依赖:你明确安装的那个包。
  • 二级依赖:它自己声明需要的包。
  • 三级及更多依赖:那些包继续声明的包。

如果改用手动下载,你需要自己找到每个包的正确版本、解压到合适目录、处理不同包要求同一依赖的不同版本,还要在升级时重复整套工作。任何一环出错,项目都可能在另一台电脑上跑不起来。

npm 最核心的价值,就是把这棵依赖树的解析、下载和安装自动化。你声明“我需要这个包”,它负责把整棵树装完。

package.json 和 node_modules 分别做什么?

npm 项目的骨架主要由两个位置构成:package.json 负责声明,node_modules 负责存放实际代码。

package.json 是项目说明书,node_modules 存放实际下载下来的包

package.json 可以理解成项目的身份证和说明书。它通常记录:

  • 名称和版本:这个项目/包叫什么,当前是哪个版本。
  • 依赖:运行时需要哪些包,开发时还需要哪些包。
  • 脚本:启动、测试、打包等可重复执行的命令。
  • 入口和其他元数据:主文件、许可证、仓库地址等。

一份最小的例子如下:

{
  "name": "date-demo",
  "version": "1.0.0",
  "scripts": {
    "start": "node index.js",
    "test": "node --test"
  },
  "dependencies": {
    "dayjs": "^1.11.0"
  },
  "devDependencies": {
    "eslint": "^9.0.0"
  }
}

两类依赖不要混用:

字段何时安装典型内容
dependencies运行项目时需要日期库、Web 框架、数据库客户端
devDependencies只在开发、测试或构建时需要代码检查、测试框架、打包工具

node_modules 则是实际下载下来的包所在的目录。程序 require() 或 import 时,通常就是从这里解析文件。它体积往往很大,而且可以根据 package.json 和 lock 文件重新生成,所以应用项目一般会把它加入 .gitignore,不提交到 Git。

可以记成一句话:package.json 说明你要什么,node_modules 保存你已经装到的东西。

依赖版本里的 ^ 和 ~ 是什么意思?

package.json 里的依赖版本通常不是写死的单个数字,而是一段允许安装的范围。这些范围来自语义化版本(Semantic Versioning,semver):版本号写成 MAJOR.MINOR.PATCH,也就是大版本、小版本和补丁。

^1.2.3 允许同一大版本内升级,~1.2.3 只允许同一小版本的补丁,三段数字分别代表大改动、小改动和修复

三段数字的含义是:

  1. MAJOR(大版本):包含不兼容的改动,升级后调用方式或行为可能变。
  2. MINOR(小版本):在保持兼容的前提下增加功能。
  3. PATCH(补丁):兼容的问题修复。

package.json 里最常见的两种符号是 ^ 和 ~:

写法含义可安装范围
^1.2.3允许同一大版本内的新功能和补丁,不跨大版本>=1.2.3 <2.0.0
~1.2.3只允许同一小版本里的补丁>=1.2.3 <1.3.0
1.2.3精确版本,不自动浮动仅 1.2.3

所以,^1.2.3 可以升到 1.9.0,但不会自动升到 2.0.0;~1.2.3 可以升到 1.2.9,但不会自动升到 1.3.0。

有一个容易忽略的边界:如果主版本是 0,npm 对 ^ 更保守。^0.2.3 的范围相当于 >=0.2.3 <0.3.0,因为 0.x 按 semver 约定仍可能包含不兼容改动。

版本要这么讲究,是因为包升级可能带来不兼容行为,轻则测试失败,重则线上功能异常。范围写得太宽,下次安装可能装到你没验证过的版本;写得太死,又会错过安全修复。这就是为什么只靠 package.json 还不够。

为什么还需要 package-lock.json?

package-lock.json 记录的是上一次安装时,每个包精确到具体版本的快照。别人拿到你的项目,照着它安装,得到的就是同一棵依赖树,而不是“范围内随便一个新版本”。

package-lock.json 锁定精确版本,避免不兼容升级把项目搞崩,从而保证环境一致

package.json 里的 ^1.2.3 只表达“可以接受哪些版本”。如果没有 lock 文件,今天安装可能得到 1.4.0,一周后别人安装可能得到 1.5.0。只要中间某个间接依赖发布了有问题的版本,两台电脑上的项目就会表现不同。

lock 文件补上的是精确结果:哪个包解析成了哪个版本、从哪里下载、内容校验值是什么。npm 在安装或更新依赖时会自动生成或更新它。

文件或目录记录什么是否提交到 Git
package.json项目信息和允许的版本范围必须提交
package-lock.json实际解析到的精确版本和依赖树应用项目应提交
node_modules下载下来的实际代码通常不提交

实践上可以按项目类型区分:

  • 应用程序(网站、服务、桌面工具):应该把 package-lock.json 提交进 Git。持续集成里优先用 npm ci:它会删除已有的 node_modules,再按 lock 文件做一次干净安装;如果 lock 和 package.json 不一致,命令会直接失败,而不是悄悄改出版本。
  • 准备发布给别人用的库:使用者安装你的包时,npm 主要看你在 package.json 里声明的版本范围,而不是你仓库里的 lock 文件。因此库作者仍要把直接依赖的范围写准确。

package.json 描述允许什么,package-lock.json 冻结实际装了什么。 两者一起,才构成可复现的安装。

npm 日常最常用的命令有哪些?

理解了声明、安装目录和 lock 文件之后,常用命令就可以按职责来记。日常最高频的是安装、添加依赖、跑脚本和发布。

常用命令包括 npm install、npm install 包名、npm run 和 npm publish

命令做什么
npm install读取 package.json 和 lock 文件,把依赖装进 node_modules
npm install <包名>安装一个新包,并写入 package.json 与 lock 文件
npm run <脚本名>执行 package.json 里 scripts 定义的命令
npm publish把当前包发布到公共仓库,让别人也能安装

对应到具体操作:

# 根据已有配置安装全部依赖
npm install

# 添加运行时依赖
npm install dayjs

# 添加开发依赖
npm install eslint --save-dev

# 执行脚本。npm start / npm test 是常用快捷方式
npm run start

# 发布自己的包。需要先登录,且包名不能冲突
npm publish

还有几个同样常用、但图里没有单独画出的命令:

命令适合场景
npm init -y生成一份初始 package.json
npm ci在 CI 或部署环境按 lock 文件做干净安装
npm uninstall <包名>卸载依赖,并同步修改 package.json
npm update在现有版本范围内更新依赖
npx <命令>运行某个包提供的命令,不一定先全局安装

npm run 之所以重要,是因为它把“这个项目怎么启动、怎么测试、怎么打包”写成了可分享的命令,而不是散落在每个人自己的备忘录里。克隆仓库的人只要安装依赖,再运行约定好的脚本即可。

什么是全局安装?

全局安装指的是 npm install -g(也可以写成 npm install --global)。它装的不是某个项目的依赖,而是装到系统或当前用户能访问的位置,让命令在任何目录都能调用。

项目依赖只作用于当前项目,npm install -g 把命令行工具装到系统里供任何地方调用

两者的差别很直接:

方式安装位置谁能用版本跟谁走
项目依赖当前项目的 node_modules这个项目package.json / lock 文件
全局安装系统或用户级目录终端里的任意目录你这台电脑当前装的那个版本

脚手架命令、本机常用的开发工具,历史上经常用 -g 安装。但这有明确边界:

  • 项目里的构建和检查工具,例如 ESLint、TypeScript、打包器,应作为项目依赖安装。这样同事克隆仓库后能用同一版本,CI 也不依赖某台电脑的全局环境。
  • 只想临时跑一次的命令,优先用 npx,不必先全局安装。
  • 不要用 sudo npm install -g 来绕过权限错误。 这会把包装到系统目录,增加权限和安全风险。更稳妥的做法是修复 npm 的安装前缀,或使用 nvm 这类 Node 版本管理器。

一句话:项目能跑起来的依赖放进项目;只有你确定要在所有项目外使用的命令行工具,才考虑全局安装。

npm 的完整工作链路是怎样的?

把前面的概念串起来,npm 的工作链路是固定的:公共仓库提供包,命令行负责下载和管理,package.json 声明需求,lock 文件锁定精确版本,node_modules 存放实际代码,最终自动搭好依赖树。

npm 的完整链路是仓库、命令行、package.json、lock 文件、node_modules,最终一行命令搭好依赖树

一次典型安装会经过这些步骤:

  1. 公共仓库汇集包:开发者把可复用代码发布到注册表。
  2. 命令行发起安装:你在项目目录执行 npm install 或 npm install <包名>。
  3. 读取声明:CLI 查看 package.json 里要哪些包、版本范围是什么。
  4. 对照快照:如果存在 package-lock.json,优先按其中的精确版本解析,保证结果可复现。
  5. 写入本地目录:把包解压到 node_modules,必要时更新 lock 文件。
  6. 展开依赖树:递归安装间接依赖,直到整棵树完整。

所以你只需要一行命令,背后那棵可能有几十甚至几百个包的依赖树就会被自动装好。日常开发看到的是命令本身;工程上真正重要的,是声明、锁定和安装结果被分成了不同文件。

npm、Yarn 和 pnpm 有什么区别?

npm 是 Node.js 默认附带的包管理器,但不是唯一选择。Yarn 和 pnpm 也能读取 package.json、安装依赖并生成 lock 文件,只是默认策略不同。

维度npmYarnpnpm
是否随 Node.js 安装是否否
lock 文件package-lock.jsonyarn.lockpnpm-lock.yaml
node_modules 形态默认扁平安装因 Yarn 版本而异通过内容寻址仓库和链接安装,结构更严格
常见选择理由官方默认,教程和示例最多历史项目、部分团队的 workspace 工作流节省磁盘、减少“幽灵依赖”
适合场景大多数个人项目和入门教程已经使用 Yarn 的代码库依赖多、对安装一致性和磁盘占用更敏感的项目

三者都在解决同一类问题:声明依赖、锁定版本、安装依赖树。对新手,先把 npm 用熟即可。团队一旦选定工具,就应只保留一种 lock 文件,不要在同一个项目里混用 npm install、yarn 和 pnpm install,否则 lock 文件会互相覆盖,安装结果变得难以预测。

使用 npm 时有哪些常见误区?

npm 能自动安装依赖,并不代表它可以替你判断包是否安全、版本是否兼容,或项目在每台机器上都会以相同方式启动。

误区真实情况更稳妥的做法
把 node_modules 提交进 Git目录很大,而且可以根据声明重新生成加入 .gitignore,提交 package.json 和 lock 文件
不提交 package-lock.json下次安装可能解析到范围内的新版本应用项目提交 lock 文件,CI 使用 npm ci
把项目工具装到全局同事和 CI 没有同一版本,脚本可能跑不起来项目依赖 + npx 或 npm run
用 sudo npm install -g 解决权限可能改写系统目录,扩大安全风险修复 npm 权限,或使用 Node 版本管理器
删除 lock 文件再安装来“修复问题”等于放弃已验证的依赖树先看报错和 npm ls,必要时再有针对地更新
只按下载量选包下载量不能代表维护状态或安全性看最近提交、issue、许可证,并关注安全公告
同一个项目混用多个包管理器lock 文件冲突,依赖树不一致团队只保留一种工具和一份 lock 文件

还要注意:语义化版本是约定,不是物理定律。包作者可能把不兼容改动发在小版本里,间接依赖也可能引入漏洞。npm audit 能列出已知漏洞,但不能替代你对直接依赖的选择和测试。

常见问题

npm 是什么?

npm 是 Node.js 生态的包管理器,也常用来指它背后的公共软件仓库。它负责安装 JavaScript 包、解析依赖树、锁定精确版本,并支持把包发布给其他人使用。

npm 和 Node.js 是什么关系?

Node.js 是 JavaScript 的运行时,负责执行代码;npm 是默认随 Node.js 一起提供的包管理器,负责获取和安排这些代码所依赖的包。没有 Node.js,npm 管理的包通常无法运行;没有包管理器,Node.js 项目很难稳定地复用现有生态。

package.json 和 package-lock.json 有什么区别?

package.json 记录项目信息和允许的依赖版本范围;package-lock.json 记录某次安装实际解析到的精确版本和依赖树。前者说明需求,后者保证别人安装时能复现同一棵树。应用项目通常两份文件都要提交。

node_modules 要不要提交到 Git?

通常不要。node_modules 体积大、文件多,而且可以用 package.json 加 lock 文件重新安装出来。应该提交的是声明和锁文件,而不是安装结果。例外很少,例如某些离线交付场景会单独打包依赖,那也不等于把它当作常规 Git 内容。

^ 和 ~ 有什么区别?

以 1.2.3 为例,^1.2.3 允许安装 1.2.3 到 2.0.0 之前的版本;~1.2.3 只允许安装 1.2.3 到 1.3.0 之前的版本。^ 更宽松,~ 更保守。主版本为 0 时,^ 的实际范围会更窄。

什么时候用全局安装,什么时候改用 Yarn 或 pnpm?

全局安装适合你想在任意目录调用、且不属于某个项目锁定版本的命令行工具。项目自己的依赖和构建工具应安装在项目内。至于 Yarn 或 pnpm,它们不是 npm 的必需替代品;如果团队已有约定、或者你明确需要 pnpm 那种更严格的依赖结构,再切换,并且全项目统一使用。

总结:npm 不只是一个下载工具

npm 是 Node.js 生态里的包管理器。它把可复用代码集中到公共仓库,用命令行帮你安装和管理,用 package.json 声明需求,用 lock 文件冻结精确版本,再用 node_modules 存放实际代码。

npm 不只是下载工具,它是公共代码市场、依赖调度中心和环境一致保障,也是进入 JavaScript 工程化的门槛

对个人项目,它让你用一行命令接上现成的函数库和工具;对团队项目,它让依赖声明可审查、安装结果可复现,减少“在我电脑上是好的”这类分歧。理解 npm,不只是记住 npm install,而是理解声明、锁定、安装和依赖树之间的分工。

所以,npm 并不只是一个下载工具。它是 Node 生态里的公共代码市场,是项目的依赖调度中心,也是保证团队环境一致的关键一环。理解了它,你才算真正踏进 JavaScript 工程化的门槛。

记住这一点:你声明的是需要哪些包,npm 负责把整棵依赖树装好,并用 lock 文件保证下次还能装成一样的结果。

参考资料

共 11 张正文配图,打包为 ZIP。