npm
把三万行依赖变成一条命令
npm 不只是一个下载工具。它同时是 registry 协议客户端、依赖解析器、锁定文件的记录者 和 脚本运行器。理解这四件事的分工,node_modules 里的绝大多数困惑就会自动消失。
npm 到底是什么:四个角色,一套文件
CLI · registry · manifest · lockfile很多人把 npm 等同于「装包的命令」,但它其实是一组约定:一个命令行客户端、一个公共仓库(registry)、两份项目描述文件(package.json 与 package-lock.json),以及一个放依赖的目录 node_modules。命令只是这四者的粘合剂。
一句话:npm 读取项目里的声明,去 registry 换回压缩包,再把结果写进 node_modules 和 lockfile。
CLI
随 Node.js 分发的命令行程序,负责解析、下载、链接、执行脚本。
Registry
包的托管服务。任何兼容该协议的仓库都能被 npm 使用(含私有源、镜像)。
package.json
项目清单:名字、版本、依赖范围、脚本。人写的那份。
lockfile
解析结果的精确快照:每个包的版本、来源、哈希。机器写的那份。
package.json 与 registry 协议。一次 npm install 发生了什么
Manifest → Resolve → Fetch → Link → Lock
执行 npm install 时,终端里只有一行转圈,背后却是五个阶段。把它们拆开看,你就知道为什么「同一个项目,两个人装出来不一样」。
重点:不确定性集中在第 ② 步。lockfile 的全部意义,就是把这一步的结果固定下来。
三个容易忽略的细节
缓存是内容寻址的
包按内容哈希存放,全局共享。断网重装同一版本通常也能成功。
.bin 不是复制
node_modules/.bin 里是指向包内可执行文件的链接,由 bin 字段生成。
postinstall 会执行代码
安装过程可能运行包自带脚本——这是供应链安全的核心风险点,--ignore-scripts 可关闭。
语义化版本:写范围,而不是写死
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.0 | 0.x 视为不稳定,次版本升级也算破坏性 |
交互 · LIVE 范围会选中哪个版本?
点一个范围,下方已发布版本中绿色为命中,实心高亮为最终解析结果(取范围内最高稳定版)。
依赖字段不止 dependencies
dependencies
运行时真正需要的包,会被打进最终产物或随服务一起部署。
devDependencies
构建、测试、格式化工具。生产安装用 --omit=dev 跳过。
peerDependencies
要求宿主项目提供的包(如 React 插件)。npm 7+ 会自动安装并检查版本。
0.x.y 处于开发期,任何版本都可能不兼容。所以 ^0.2.3 不会升到 0.3.0——这常常让「为什么依赖没更新」变成一场考古。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 要固定树结构的原因。
node_modules 只放符号链接。省磁盘、无幽灵依赖,但要求工具链兼容 symlink。npm 本身没有这种模式,只有扁平 + 嵌套。package-lock.json:把「碰运气」变成「可复现」
install vs cipackage.json 写的是意图(我想要 ^4.18.0),package-lock.json 记录的是事实(那天实际装的是 4.18.3,来自哪个地址,哈希是多少)。它应该被提交进版本库,并且由 npm 自动维护,不要手改。
// 名字 + 版本 + 来源 + 完整性哈希,一个都不可少 "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,就是一次隐形的赌博。scripts 与 npx:项目自带的任务系统
run-script · lifecycle · execpackage.json 的 scripts 是一层极薄的约定:把长命令写成短名字,让所有人用同一套入口。执行 npm run build 时,npm 会临时把 node_modules/.bin 加进 PATH,并自动运行同名的 pre* / post* 钩子。
"scripts": { "dev": "vite", "prebuild": "rimraf dist", // 自动先跑 "build": "tsc -p . && vite build", "postbuild": "node scripts/check-dist.mjs", // 自动后跑 "test": "vitest run", "lint": "eslint . --fix" }
记住:pre / post 前缀是 npm 的特殊约定,不是你自己定义的函数。
npx:用过即走,不污染全局
npx cowsay hi 会优先使用本地已安装的可执行文件;找不到时临时下载到缓存里运行,结束后不留在全局。npx 实际上是 npm exec 的简写。
适合 npx 的场景
- 一次性脚手架:
npx create-vite@latest - 临时检查:
npx tsc --noEmit - 跑不同版本的 CLI 对比行为
不要用 npx 的场景
- CI / 团队共享流程 —— 版本不可控
- 需要固定工具版本的项目脚本
- 来源不明的包名(会直接执行代码)
发布一个包:从本地到 registry
version · pack · publish发布是不可逆的:同一个版本号发布后不能再覆盖(npm 只允许撤销或废弃)。因此发布前先看清「到底会传上去哪些文件」,是每个包作者的基本功。
npm view <name> 查占用;公开包可用 @scope/name。npm version patch|minor|major,同时打 git tag。npm pack --dry-run 查看将被发布的文件清单。npm publish,默认推上 latest 标签。# 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 白名单
在 package.json 写 "files": ["dist"],只发布必要产物,比 .npmignore 更可控。
dist-tags
latest 是默认安装目标;预发可用 next,用户需显式 @next 安装。
provenance
配合 CI 的 OIDC 发布,可生成来源证明,让使用者验证包确实由该仓库构建。
npm unpublish pkg@1.0.0;更常见且更安全的做法是 npm deprecate pkg@1.0.0 "请升级到 1.0.1",再发一个新版本修复。常见故障:按报错对症下药
ERESOLVE · EINTEGRITY · E404npm 的报错通常信息量很大,只是被一屏警告埋住了。下表是最常见的几类,以及优先尝试的排查动作。
| 现象 / 报错 | 真实原因 | 优先动作 |
|---|---|---|
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 可靠,但也会让依赖树偏离上游预期,要写清原因。
"overrides": { "minimist": "^1.2.8", "some-pkg": { "nested-dep": "2.0.0" } }
私有源与镜像:用 .npmrc 表达
# 只把 @company 开头的包指向私有源,其余走公共源 @company:registry=https://npm.company.com/ //npm.company.com/:_authToken=${NPM_TOKEN} # 公共依赖走镜像(示例) registry=https://registry.npmmirror.com/
.npmrc > 用户 ~/.npmrc > 全局配置 > 内置默认值。用 npm config list 可以看到最终生效值——排查「为什么走了另一个源」时非常有用。命令速查:按场景记,不按字母记
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 outdated | current / wanted / latest 三列 |
| 为什么装了两个版本 | npm ls pkg / npm explain pkg | 定位依赖路径 |
| 跑脚本 | npm run <name> | 参数用 -- 透传:npm run test -- --watch |
| 一次性执行 CLI | npx <cmd> | 不装全局 |
| 安全审计 | npm audit / npm audit fix | 先看清变更范围再 fix |
| 发布 | npm publish --access public | 版本号不可复用 |
| 看配置最终值 | npm config list | 排查源 / 代理 / token |
一页速记
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 的不确定性就基本被关进笼子里了。