npm 与依赖管理
本合集目录
本章目录
单册说明:本文件是卷 3 的第 5 章,可独立阅读。前置:第 4 章(ESM 模块)。本章让"这个项目需要什么、怎么启动、怎么构建"从口头约定变成两个文件:
package.json与package-lock.json。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 3 · 工程化与版本控制(第 5 / 7 章) |
| 前置章节 | 3.4 从脚本到模块 |
| 本章产出 | 一份写清字段的 package.json · 一份提交进仓库的 package-lock.json · 三个可用的 npm script |
| 对应代码 | dudao/package.json、dudao/package-lock.json(新增) |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 拿到一个别人的项目,知道先看 package.json 的哪三处,再决定敲哪条命令 |
3.5.1 一句话结论:package.json 是意图,package-lock.json 是事实
package.json 写的是"我需要 Vite,版本别低于 7"——这是意图,是一个范围。package-lock.json 写的是"2026 年 11 月 17 日这天,我实际装的是 Vite 7.1.2,它的四十几个依赖分别是哪些版本、从哪下载、内容哈希是多少"——这是事实,是精确到每一个包的一张照片。
真实失败场景:你把项目发给同学,他 npm install 之后页面起不来,报 Cannot find module @rollup/rollup-win32-x64-msvc。你们俩都没改代码。原因是他没拿到你的 lock 文件(或者你根本没提交),npm 按 package.json 的范围重新算了一遍依赖树,装出来的组合和你不一样。
3.5.2 原理:package.json、lock 与 semver
① package.json 里真正重要的只有六个字段
npm init -y 会生成一堆字段,大部分用不上。需要你亲手管的是这些:
| 字段 | 作用 | 本项目怎么写 | 不写会怎样 |
|---|---|---|---|
name |
包名,也决定默认的项目标识 | dudao |
用目录名,可能含中文或大写,某些工具会报错 |
version |
语义化版本 | 0.1.0 |
默认 1.0.0,不影响本地开发 |
private |
设为 true 表示"不发布到公共仓库" |
true |
手滑 npm publish 会把项目推到公共源 |
type |
让 Node 把 .js 当 ESM 解析 |
"module" |
import 语法在 Node 里报 Cannot use import statement outside a module |
scripts |
命令别名 | 见下 | 每次都要敲一长串参数,且团队成员各敲各的 |
dependencies / devDependencies |
依赖清单 | 由 npm install 自动维护 |
别人不知道要装什么 |
type: "module" 值得单独说一句。浏览器里 <script type="module"> 已经声明了模块,Node 没有 HTML,只能靠这个字段判断。同一个 import 语句,在浏览器能跑、在 Node 里报错,十有八九就是漏了这个字段。
② dependencies 与 devDependencies
| 类别 | 含义 | 例子 | 生产环境要不要 |
|---|---|---|---|
dependencies |
代码运行时要用的库 | 日期处理、HTTP 客户端 | 要 |
devDependencies |
只在开发、构建、测试时用 | Vite、ESLint、测试框架 | 不要(产物里已经打包好了) |
Vite 属于 devDependencies:它把你的源码变成 dist/,而 dist/ 里没有任何一行 Vite 的代码。所以服务器上只需要 dist/,连 node_modules 都不用传。
装到 dev 里的写法是 -D:
npm install -D vite
判断标准很简单:这个包会不会被打进最终产物、或者在线上运行时被 import?会就是 dependencies,不会就是 devDependencies。装错位置不会立刻报错,但会让部署时的 npm ci --omit=dev 少装东西,线上半夜崩。
③ semver:^ 和 ~ 到底放行多少
版本号 主.次.补丁(2.4.1)的约定是:主版本改动=不兼容,次版本=加功能且兼容,补丁=修 bug 且兼容。npm 的写法是在这个基础上划一个范围:
| 写法 | 等价范围 | 放行到什么程度 | 风险 |
|---|---|---|---|
2.4.1 |
只有 2.4.1 |
一步不放 | 最稳,但拿不到安全补丁 |
~2.4.1 |
>=2.4.1 <2.5.0 |
只收补丁 | 低 |
^2.4.1 |
>=2.4.1 <3.0.0 |
收补丁 + 次版本 | 中(默认值) |
* / latest |
任意 | 什么都收 | 高,别用 |
>=2.4.1 |
无上限 | 包括 3.0、4.0 | 极高 |
有一个例外必须记住:主版本为 0 时,^ 的规则更保守。 ^0.2.3 等价于 >=0.2.3 <0.3.0,因为 0.x 被约定为"不稳定"。很多工具在 1.0 之前频繁改 API,这条规则就是在防这个。
那为什么还要用范围? 因为要能拿到安全补丁。理想状态是"范围放宽、lock 锁死":package.json 允许 ^7.0.0,但 package-lock.json 把实际版本钉在 7.1.2,两者配合,既有升级空间,又保证每次装出来一样。
④ lock 文件锁的是整棵树
这是全章最容易被低估的一点。你只写了一个依赖:
"devDependencies": { "vite": "^7.0.0" }
但 Vite 自己依赖 esbuild、rollup、postcss 等三十多个包,这些包又各自依赖别的包。package-lock.json 记录的是这整棵树,每个节点包含三样东西:
| 记录项 | 作用 |
|---|---|
version |
精确版本,不带 ^ |
resolved |
从哪个地址下载的压缩包 |
integrity |
内容哈希,包被篡改就装不上 |
所以 lock 文件通常有几千行、几十万字节,而且要提交。它不是缓存,是"可复现"的凭证。 没有它,"在我电脑上能跑"就是一句无法验证的话。
⑤ node_modules 为什么不提交
| 原因 | 具体后果 |
|---|---|
| 体积 | 一个 Vite 项目装完约 30–80 MB,几十万个文件;push 会卡到超时 |
| 平台相关 | 里面有编译好的二进制(如 esbuild、rollup 的平台包),Windows 的拿到 Linux 上直接不能用 |
| 可重建 | 有 package.json + lock,一条 npm ci 就能一模一样地还原 |
| 审查噪音 | PR 里出现几万行依赖代码,真正改动被淹没 |
删了怎么恢复?用 npm ci,不是 npm install。
| 命令 | 读什么 | 会不会改 lock | 会不会删 node_modules | 用途 |
|---|---|---|---|---|
npm install |
package.json + lock(参考) |
可能改 | 否,增量更新 | 日常加包、改依赖 |
npm ci |
只读 lock | 绝不改 | 会先整个删掉再装 | CI、部署、拿到新项目第一次装 |
npm ci 在 lock 与 package.json 不一致时会直接失败,而不是悄悄帮你修。这是特性:它保证"装出来的就是锁住的那份",装不出来说明有人改了 package.json 却没更新 lock,应该被拦下。
⑥ scripts:把长命令收进一个词
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
}
之后 npm run dev 就等于 npx vite。三个好处:团队里所有人敲同一个词;CI 里只写 npm run build,换工具不用改流水线;npm run 不带参数会列出所有可用脚本——拿到新项目,先敲这一条。
pre / post 前缀是自动钩子:prebuild 会在 build 前自动执行。少用,因为它让"我敲了一条命令,实际跑了三条"变得不透明。
⑦ 装不上的三种原因
| 类型 | 报错关键词 | 真实原因 | 修法 |
|---|---|---|---|
| 网络 | ETIMEDOUT、ECONNRESET、npm error network |
连不上源、代理没配、公司网络拦截 | 先重试;再按官方文档配镜像;代理要单独给 npm 配 |
| 版本冲突 | ERESOLVE、unable to resolve dependency tree |
两个包对同一个依赖要求了互斥的版本 | 看报错里的 Found: / Could not resolve,统一版本或升级其中一个 |
| 权限 | EACCES、EPERM、operation not permitted |
全局目录属主是 root;文件被杀毒/编辑器占用 | 改 npm 全局前缀到用户目录,不要 sudo npm install |
三类的分界线在报错第一行的 code。 看到 code 就知道该找网络、找版本、还是找权限,不用读完整篇日志。
⑧ 每加一个依赖,都是一次长期承诺
node_modules 里那四十三个包不是你写的,但出了问题要你修;它们升级、弃用、被投毒,风险都算在你头上。所以加依赖前问三个问题:
| 问题 | 如果答案是"否" | 后果 |
|---|---|---|
| 这段逻辑我自己写要超过半天吗? | 能用二十行写完的日期格式化,就别装一个库 | 省下的时间不够未来处理它的升级 |
| 它最近一年还在维护吗? | 看仓库的提交记录与 issue 响应 | 你会在某个 Node 版本升级时被迫接手 |
| 它会不会拖进几十个间接依赖? | npm ls <包名> 或看 lock 里的条目 |
一个包拖进四十个包,攻击面翻倍 |
本卷只装一个 Vite,是刻意的。 项目越小,越能看清每个依赖到底在替你做什么。卷 4 之后依赖会自然变多(React、Next),那时你已经知道该看 lock 里的什么了。
3.5.3 动手:让「读到」有一个真正的工程入口
第 1 步:初始化
在 dudao/ 根目录(有 index.html 的那层)执行:
npm init -y
形如:
{
"name": "dudao",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}
第 2 步:手工改成"这是个应用,不是库"
{
"name": "dudao",
"version": "0.1.0",
"private": true,
"type": "module",
"description": "读到:个人摘录与关键词统计",
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
}
}
删掉 main(那是给被 require 的库用的)、keywords、author、license——应用不需要这些。保留 private: true,防止误发布。
也可以不手工编辑,用命令改:
npm pkg set name=dudao version=0.1.0 private=true type=module
npm pkg delete main keywords author license
第 3 步:装 Vite 到 devDependencies
npm install -D vite
形如:
added 43 packages, and audited 44 packages in 8s
12 packages are looking for funding
run `npm fund` for details
found 0 vulnerabilities
此时三件事同时发生:package.json 多了 devDependencies;package-lock.json 被创建;node_modules/ 出现。验证版本:
npx vite --version
形如:
vite/7.1.2 ...
npx 会优先用本地 node_modules 里的可执行文件,而不是去下载。
第 4 步:看清 lock 里有什么
head -40 package-lock.json
形如:
{
"name": "dudao",
"version": "0.1.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "dudao",
"version": "0.1.0",
"devDependencies": { "vite": "^7.1.2" }
},
"node_modules/@esbuild/win32-x64": {
"version": "0.25.9",
"resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.9.tgz",
"integrity": "sha512-...",
"cpu": ["x64"],
"os": ["win32"],
"optional": true
}
}
}
注意 node_modules/@esbuild/win32-x64:你的 Windows 机器上,lock 里会记录 Windows 专用的可选包。 这些 optional 条目让 Linux 服务器能跳过它们、装自己的版本,所以同一个 lock 可以跨平台使用——前提是 lock 被完整保留。
数一下总包数:
grep -c '"resolved"' package-lock.json
形如 43。你只写了一个依赖,它带来了四十三个包。这就是"锁整棵树"的含义。
第 5 步:模拟"新同事第一次装"
先把依赖整个删掉,再用 ci 还原:
rm -rf node_modules
npm ci
形如:
added 43 packages, and audited 44 packages in 2s
npm ci 比 npm install 快,因为它不做版本求解,直接按 lock 下载。部署脚本里永远写 ci。
第 6 步:验证脚本入口
此时 vite.config.js 还没建,npm run dev 会以 dudao/ 为根起服务,这已经能跑(第 6 章再正式迁移):
npm run dev
形如:
VITE v7.1.2 ready in 312 ms
➜ Local: http://localhost:5173/
➜ Network: use --host to expose
➜ press h + enter to show help
打开 http://localhost:5173/,页面应该和 python -m http.server 时一样。Ctrl + C 停掉。
最后提交:
git add package.json package-lock.json
git commit -m "chore: 引入 npm 与 Vite 依赖"
确认 node_modules/ 没有出现在 git status 里——第 3 章的 .gitignore 应该已经挡住了它。
3.5.4 三个坑
坑 1:把 node_modules 提交了
症状:git add . 之后 git status 里冒出几千个文件;git push 卡在 Writing objects: 62% 十几分钟,最后断掉:
error: RPC failed; HTTP 413 curl 22 The requested URL returned error: 413
send-pack: unexpected disconnect while reading sideband packet
fatal: the remote end hung up unexpectedly
即使推上去了,单个超过 100 MB 的文件也会被远端直接拒收。
成因:.gitignore 里写的是 node_modules(没写斜杠)也许没问题,但如果你在子目录里也有一份,或者 .gitignore 是后来才加的,已经进过索引的文件不受忽略规则影响。
修法:
git rm -r --cached node_modules
git commit -m "chore: 停止跟踪 node_modules"
如果已经推送且历史里有大文件,仓库体积不会因为这次删除而变小——需要重写历史(git filter-repo --path node_modules --invert-paths)才能真减。所以第一次 git add 之前就把 .gitignore 写对,成本差一百倍。
坑 2:删了 lock,装出另一棵树
症状:报错指向一个你从没听说过的包:
Error: Cannot find module @rollup/rollup-win32-x64-msvc
或者同事那边 Vite 版本从 7.1 变成了 7.4,某个配置项行为变了,构建产物不对。
成因:lock 文件丢失、被加进 .gitignore、或者有人 rm package-lock.json 后重装。npm 只能按 package.json 的范围重新求解,装出"当下最新且满足范围"的组合——和原来那棵不一样。上面那个 @rollup/rollup-* 报错是经典案例:平台专用的可选依赖没被正确装上,通常发生在 lock 缺失或 node_modules 被跨平台拷贝时。
修法:从版本库里恢复 lock,再 npm ci:
git checkout HEAD -- package-lock.json
rm -rf node_modules
npm ci
如果 lock 已经彻底没了,只能删掉 node_modules 和 lock 重装一次,然后把新 lock 提交——这一次之后,它就是团队共享的事实。
坑 3:权限错误,然后 sudo 把问题放大
症状:
npm error code EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules/vite
npm error errno -13
Windows 上则可能是 EPERM: operation not permitted, rename ...。
成因:Linux/macOS 上全局目录属主是 root;Windows 上多半是文件正被编辑器、终端或杀毒软件占用(尤其是刚 Ctrl+C 停掉的 dev server 还没释放文件句柄)。
修法:Windows 先关掉占用的进程再重试。Linux/macOS 不要用 sudo npm install——它会让 node_modules 里全是 root 拥有的文件,下次普通用户跑构建就报 EACCES,越修越乱。正确做法是把全局前缀改到用户目录:
npm config get prefix
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
然后把 ~/.npm-global/bin 加进 PATH。更省事的方案是用版本管理器(nvm 一类)装 Node,它天然把全局目录放在用户空间,不会碰系统目录。
本章验收
-
package.json里有private: true、type: "module"和三个 scripts,没有多余的main -
package-lock.json已提交,grep -c '"resolved"'的数量大于依赖个数(说明锁了整棵树) -
node_modules/不在版本控制里,git check-ignore -v node_modules能指出规则 - 删掉
node_modules后npm ci能完整还原,页面照常启动 - 能说出
^1.2.3、~1.2.3、1.2.3各自允许装到什么版本 - 拿到一个陌生项目,会先看
package.json的scripts、type、依赖分区,再决定命令
自测
Q1:package.json 里写 "vite": "^7.0.0",lock 里写 7.1.2。如果明天 Vite 发布 7.2.0,你 npm ci 会装哪个?为什么?
看答案
还是 7.1.2。`npm ci` 只认 lock,不解析范围、不检查有没有新版本,这是它"可复现"的定义。想升级必须显式执行 `npm update vite` 或 `npm install -D vite@latest`,这会更新 lock,然后你把新 lock 提交,团队才一起升。Q2:为什么 Vite 装在 devDependencies 而不是 dependencies?
看答案
因为它是构建工具,产物 `dist/` 里不包含它的运行时代码,线上服务器也不需要它。放在 dev 里,部署时 `npm ci --omit=dev` 可以少装几十个包,镜像更小、攻击面更小。判断依据是"线上运行时会不会 import 它",而不是"重不重要"。Q3:同事说"我 npm install 就好了,为什么要用 npm ci"?你怎么解释两者的差别?
看答案
`npm install` 会参考 `package.json` 的范围做版本求解,可能更新 lock、可能装出和原来不同的树,适合日常加包。`npm ci` 只读 lock、先删 `node_modules` 再全量安装、lock 与 `package.json` 不一致时直接报错,适合 CI 与部署。部署要的是"和测试过的那份完全一致",所以必须用 `ci`。下一步
依赖装好了,npm run dev 也能起服务。但它现在只是"把目录当静态根",还没有构建、没有环境变量、没有产物目录。下一章把这些补齐,产出可以整包发布的 dist/。