跳到正文
零到全栈 · 卷 3 · 工程化与版本控制

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/。

→ 卷3-06-Vite开发与构建.md