DevOps Tool · Package Manager

npm
把三万行依赖变成一条命令

npm 不只是一个下载工具。它同时是 registry 协议客户端、依赖解析器、锁定文件的记录者 和 脚本运行器。理解这四件事的分工,node_modules 里的绝大多数困惑就会自动消失。

npm, Inc. 2010 年发布 随 Node.js 一起安装 registry: registry.npmjs.org semver 语义化版本 当前大版本 npm 10 / 11
01

npm 到底是什么:四个角色,一套文件

CLI · registry · manifest · lockfile

很多人把 npm 等同于「装包的命令」,但它其实是一组约定:一个命令行客户端、一个公共仓库(registry)、两份项目描述文件(package.json 与 package-lock.json),以及一个放依赖的目录 node_modules。命令只是这四者的粘合剂。

你的项目 package.json 声明依赖与脚本 package-lock.json 锁定精确版本 node_modules/ 解析后的依赖树实体 npm CLI 解析依赖 · 取包 · 建树 执行 scripts · 校验完整性 node_modules/.bin/npm Registry(远端仓库) GET /express → 所有版本 + 元数据 JSON GET /express/-/…tgz → 压缩包 + shasum 默认地址 registry.npmjs.org 读取 写入 请求 tarball

一句话:npm 读取项目里的声明,去 registry 换回压缩包,再把结果写进 node_modules 和 lockfile。

$

CLI

随 Node.js 分发的命令行程序,负责解析、下载、链接、执行脚本。

☁

Registry

包的托管服务。任何兼容该协议的仓库都能被 npm 使用(含私有源、镜像)。

◇

package.json

项目清单:名字、版本、依赖范围、脚本。人写的那份。

🔒

lockfile

解析结果的精确快照:每个包的版本、来源、哈希。机器写的那份。

别把 npm 和 Node 混为一谈。 Node.js 是运行时,npm 是它的包管理器。yarn / pnpm 可以替换 npm 的客户端角色,但读写的仍是同一套 package.json 与 registry 协议。
02

一次 npm install 发生了什么

Manifest → Resolve → Fetch → Link → Lock

执行 npm install 时,终端里只有一行转圈,背后却是五个阶段。把它们拆开看,你就知道为什么「同一个项目,两个人装出来不一样」。

1读清单读取 package.json 的 dependencies / devDependencies,以及已有 lockfile。
2解析版本把 semver 范围展开成具体版本,构建完整依赖树,处理冲突。
3取包先查本地缓存(内容寻址),缺失才去 registry 下载 tarball。
4落盘解压进 node_modules,建立嵌套结构,链接 .bin 可执行文件。
① 读清单 package.json + lockfile ② 解析版本 semver 范围 → 精确版本树 ③ 取包 cache → registry tarball + 哈希校验 ④ 落盘 node_modules/ + .bin 软链 ⑤ 写锁 package-lock 记录整棵树 人声明的意图 唯一容易产生分歧的一步 ~/.npm/_cacache 扁平化 + 冲突嵌套 保证下次装得一样 下一次 install 若 lockfile 命中,②③ 几乎全部跳过

重点:不确定性集中在第 ② 步。lockfile 的全部意义,就是把这一步的结果固定下来。

三个容易忽略的细节

◎

缓存是内容寻址的

包按内容哈希存放,全局共享。断网重装同一版本通常也能成功。

↗

.bin 不是复制

node_modules/.bin 里是指向包内可执行文件的链接,由 bin 字段生成。

!

postinstall 会执行代码

安装过程可能运行包自带脚本——这是供应链安全的核心风险点,--ignore-scripts 可关闭。

03

语义化版本:写范围,而不是写死

SemVer · range · resolve

版本号 MAJOR.MINOR.PATCH 表达三层承诺:主版本不兼容、次版本新增功能且向后兼容、修订号只修 bug。依赖里写的通常不是某个版本,而是一个可接受范围;npm 在范围内挑最高版本。

写法等价范围含义
1.2.3=1.2.3精确锁定,不留余地
~1.2.3>=1.2.3 <1.3.0只接受修订号升级(补丁)
^1.2.3>=1.2.3 <2.0.0接受兼容升级(npm 默认写入的写法)
1.x / 1>=1.0.0 <2.0.0锁主版本,次版本随便升
* / latest任意稳定版完全放开,通常只用于一次性试验
^0.2.3>=0.2.3 <0.3.00.x 视为不稳定,次版本升级也算破坏性

交互 · LIVE 范围会选中哪个版本?

点一个范围,下方已发布版本中绿色为命中,实心高亮为最终解析结果(取范围内最高稳定版)。

依赖字段不止 dependencies

dep

dependencies

运行时真正需要的包,会被打进最终产物或随服务一起部署。

dev

devDependencies

构建、测试、格式化工具。生产安装用 --omit=dev 跳过。

peer

peerDependencies

要求宿主项目提供的包(如 React 插件)。npm 7+ 会自动安装并检查版本。

为什么 0.x 是个坑? 按 SemVer 规范,0.x.y 处于开发期,任何版本都可能不兼容。所以 ^0.2.3 不会升到 0.3.0——这常常让「为什么依赖没更新」变成一场考古。
04

node_modules:一棵被压扁的树

Hoisting · nesting · peer

逻辑上依赖是一棵树,物理上 node_modules 却是尽量扁平的:能提升到顶层的包就提升,只有版本冲突的才在需要它的包下面再嵌一层。Node 的查找规则是「从当前目录逐级向上找 node_modules」,扁平化正是利用了这个规则。

交互 · VIEW 同一个依赖树,三种落盘形态

场景:a 依赖 b@1,c 依赖 b@1;后来 a 升级并要求 b@2,冲突就出现了。

磁盘上的 node_modules
说明

扁平化带来的两个副作用

  • 幽灵依赖(phantom dependency):你的代码可以直接 require 一个没写进 package.json 的包,只因为别人把它提升到了顶层。某天别人删依赖,你就炸了。
  • 提升结果依赖安装顺序:顶层位置先到先得,所以不同机器可能得到不同的树形——这正是 lockfile 要固定树结构的原因。
pnpm 的解法:不提升,所有包存在内容寻址仓库里,node_modules 只放符号链接。省磁盘、无幽灵依赖,但要求工具链兼容 symlink。npm 本身没有这种模式,只有扁平 + 嵌套。
05

package-lock.json:把「碰运气」变成「可复现」

install vs ci

package.json 写的是意图(我想要 ^4.18.0),package-lock.json 记录的是事实(那天实际装的是 4.18.3,来自哪个地址,哈希是多少)。它应该被提交进版本库,并且由 npm 自动维护,不要手改。

package-lock.json(节选) lockfileVersion 3
// 名字 + 版本 + 来源 + 完整性哈希,一个都不可少
"node_modules/express": {
  "version": "4.19.2",
  "resolved": "https://registry.npmjs.org/express/-/express-4.19.2.tgz",
  "integrity": "sha512-…",
  "dependencies": { "accepts": "~1.3.8" }
}

日常 npm install

  • 读 package.json,必要时更新 lockfile
  • 会安装、升级、删除包
  • 缺少 lockfile 时现场解析,结果可能因时间而异
  • 适合开发时新增依赖

CI / 部署 npm ci

  • 先删掉 node_modules,再严格按 lockfile 安装
  • lockfile 缺失或与清单不一致 → 直接失败
  • 不改写 lockfile,通常更快
  • 保证构建产物可追溯、可复现
判断标准很简单:需要「可能改变依赖」时用 npm install <pkg>;需要「一分不差地重放」时用 npm ci。CI 里出现 install 且没提交 lockfile,就是一次隐形的赌博。
06

scripts 与 npx:项目自带的任务系统

run-script · lifecycle · exec

package.json 的 scripts 是一层极薄的约定:把长命令写成短名字,让所有人用同一套入口。执行 npm run build 时,npm 会临时把 node_modules/.bin 加进 PATH,并自动运行同名的 pre* / post* 钩子。

package.json scripts
"scripts": {
  "dev": "vite",
  "prebuild": "rimraf dist",          // 自动先跑
  "build": "tsc -p . && vite build",
  "postbuild": "node scripts/check-dist.mjs", // 自动后跑
  "test": "vitest run",
  "lint": "eslint . --fix"
}
prebuild 清理旧产物 build 真正的构建命令 postbuild 校验 / 上报 / 打包 任一环节 exit code ≠ 0 → 整条链立即中断 这些脚本运行在项目根目录,PATH 里包含 node_modules/.bin

记住:pre / post 前缀是 npm 的特殊约定,不是你自己定义的函数。

npx:用过即走,不污染全局

npx cowsay hi 会优先使用本地已安装的可执行文件;找不到时临时下载到缓存里运行,结束后不留在全局。npx 实际上是 npm exec 的简写。

适合 npx 的场景

  • 一次性脚手架:npx create-vite@latest
  • 临时检查:npx tsc --noEmit
  • 跑不同版本的 CLI 对比行为

不要用 npx 的场景

  • CI / 团队共享流程 —— 版本不可控
  • 需要固定工具版本的项目脚本
  • 来源不明的包名(会直接执行代码)
07

发布一个包:从本地到 registry

version · pack · publish

发布是不可逆的:同一个版本号发布后不能再覆盖(npm 只允许撤销或废弃)。因此发布前先看清「到底会传上去哪些文件」,是每个包作者的基本功。

1确认名字先 npm view <name> 查占用;公开包可用 @scope/name。
2升版本npm version patch|minor|major,同时打 git tag。
3预演内容npm pack --dry-run 查看将被发布的文件清单。
4发布npm publish,默认推上 latest 标签。
终端 publish 流程
# 1. 登录(CI 里用 NODE_AUTH_TOKEN 代替)
npm login

# 2. 升版本:自动改 package.json + 生成 commit + tag
npm version minor -m "chore: release v1.3.0"

# 3. 先看打包内容,避免把测试 / 密钥发出去
npm pack --dry-run

# 4. 发布公开的 scoped 包
npm publish --access public
files

files 白名单

在 package.json 写 "files": ["dist"],只发布必要产物,比 .npmignore 更可控。

tag

dist-tags

latest 是默认安装目标;预发可用 next,用户需显式 @next 安装。

✓

provenance

配合 CI 的 OIDC 发布,可生成来源证明,让使用者验证包确实由该仓库构建。

发错了怎么办? 24 小时内、且没有其他包依赖时,可以 npm unpublish pkg@1.0.0;更常见且更安全的做法是 npm deprecate pkg@1.0.0 "请升级到 1.0.1",再发一个新版本修复。
08

常见故障:按报错对症下药

ERESOLVE · EINTEGRITY · E404

npm 的报错通常信息量很大,只是被一屏警告埋住了。下表是最常见的几类,以及优先尝试的排查动作。

现象 / 报错真实原因优先动作
ERESOLVE peer 冲突两个包要求同一个 peer 的不同主版本npm ls <pkg> 找冲突源;优先升级发冲突的包
EINTEGRITY缓存或下载内容与 lockfile 哈希不符npm cache verify,再删掉损坏条目重装
E404包名 / scope / registry 配错,或私有包未登录检查 .npmrc 的 registry 与 token
EACCES全局目录权限不足改用 nvm 等版本管理器,别用 sudo 装全局包
Cannot find module没装依赖、装到了 dev 依赖、或幽灵依赖用 npm ci 重装;把直接依赖显式写进清单
安装特别慢默认源远、网络抖动、依赖树过大换镜像源;npm ci --prefer-offline

定位依赖从哪来

终端 排查
# 谁引入了这个包?为什么装了两个版本?
npm ls react
npm explain react

# 哪些依赖落后于最新版
npm outdated

# 合并可合并的重复版本,减小体积
npm dedupe

# 已知漏洞扫描(按严重级别过滤)
npm audit --audit-level=high

如果某个间接依赖必须被强行固定,npm 8.3+ 提供了 overrides。它比手改 lockfile 可靠,但也会让依赖树偏离上游预期,要写清原因。

package.json overrides
"overrides": {
  "minimist": "^1.2.8",
  "some-pkg": { "nested-dep": "2.0.0" }
}

私有源与镜像:用 .npmrc 表达

.npmrc 项目级配置
# 只把 @company 开头的包指向私有源,其余走公共源
@company:registry=https://npm.company.com/
//npm.company.com/:_authToken=${NPM_TOKEN}

# 公共依赖走镜像(示例)
registry=https://registry.npmmirror.com/
配置有层级:项目 .npmrc > 用户 ~/.npmrc > 全局配置 > 内置默认值。用 npm config list 可以看到最终生效值——排查「为什么走了另一个源」时非常有用。
09

命令速查:按场景记,不按字母记

cheat sheet
想做这件事命令备注
初始化项目npm init -y生成默认 package.json;npm init -w 处理 workspaces
安装全部依赖npm install / npm ci开发用前者,CI 用后者
新增运行时依赖npm i express默认写入 dependencies,版本用 ^
新增开发依赖npm i -D vitest-D = --save-dev
安装确切版本npm i pkg@1.2.3也可写 tag:pkg@next
删除依赖npm uninstall pkg同时更新 lockfile
只装生产依赖npm ci --omit=dev部署镜像常用
查看可升级项npm outdatedcurrent / wanted / latest 三列
为什么装了两个版本npm ls pkg / npm explain pkg定位依赖路径
跑脚本npm run <name>参数用 -- 透传:npm run test -- --watch
一次性执行 CLInpx <cmd>不装全局
安全审计npm audit / npm audit fix先看清变更范围再 fix
发布npm publish --access public版本号不可复用
看配置最终值npm config list排查源 / 代理 / token
10

一页速记

Takeaways

心智模型

  • package.json = 意图(范围)
  • lockfile = 事实(精确树)
  • node_modules = 结果(可随时重建)
  • registry = 内容来源

日常流程

  • 拉代码后:npm ci
  • 加依赖:npm i pkg
  • 升依赖:npm i pkg@latest
  • 提交时:一并提交 lockfile

CI / 部署

  • npm ci --omit=dev
  • 用 NODE_AUTH_TOKEN 登录私有源
  • 缓存 ~/.npm 加速
  • 别在 CI 里跑会改 lockfile 的命令

安全底线

  • 不把密钥写进 .npmrc 提交
  • 留意 postinstall 脚本
  • 定期 npm audit
  • 依赖不是越多越好

概念对照表

概念一句话定义对应文件 / 命令
manifest项目与依赖范围的声明package.json
lockfile解析后的精确依赖树快照package-lock.json
registry按 HTTP 协议提供包元数据与 tarball 的服务registry.npmjs.org / .npmrc
semver range一组可接受的版本集合^ ~ x *
hoisting把依赖尽量提升到顶层 node_modules 以去重npm 3+ 的默认行为
peer dependency由宿主提供的依赖,插件类包常用peerDependencies
dist-tag指向某个版本的别名latest / next
workspaces单仓库多包管理workspaces + npm i -w
最后一句:把 node_modules 当成可丢弃的编译产物,把 lockfile 当成要评审的源码。做到这两点,npm 的不确定性就基本被关进笼子里了。
npm 图解 · Node 包管理基础 registry · semver · lockfile