npm 与包管理：敲下 npm install 之后，那些包是从哪来的

0030 秒速览：三句话，和你的下一个动作

读完这篇你能做到三件事：① 打开任何一个项目的 package.json，说出「它要哪些包、哪些只在开发时用」；② 知道 npm install 和 npm ci 的区别，以及那个长得像乱码的锁文件为什么必须提交到 git（管理代码版本的工具）；③ 在装一个包之前，知道它会执行别人写的代码，以及现在该怎么应对。

如果只记三句话

接下来 60 秒：你的第一个动作

打开一个你手上有过 node_modules 的项目（从 AI 那里拿来的半成品也算），在项目目录里依次敲这三条：

node -v            # 你装的 Node 是哪个版本
npm -v             # 顺带装上的 npm 是哪个版本
npm ls --depth=0   # 只看「你亲自要的」那几层
npm ls --all       # 看整棵树——你会看到比上一条多几十倍的名字

这两条 ls 的对比，就是这篇要讲的全部内容。第一条列出来的，通常只有五六个到几十个；第二条列出来的，往往是几百上千行。多出来的那些，你一个字都没写过，但它们必须被装上——这就是「包管理」这四个字真正在管的东西。

关键数字（先有个量级感）

不确定自己该看哪一节？

01npm 是三个东西共用一个名字

先纠正一个连很多老手都在传的错

你可能在无数教程里见过这句话：「npm 是 Node Package Manager 的缩写」。这句话是错的，而且官方明确反对。

npm 自己的品牌用词政策里写着："npm" should never be used or explained as an acronym.（npm 不应被当作缩写来使用或解释。）我把 npm 官方文档仓库里的 745 个文档文件全量检索过一遍，Node Package Manager 这个词组一次都没有出现过；而 acronym（缩写）这个词只出现过一次，就是上面那句否认。（出处与复核方法见 §15。）

它的三个身份，各自是什么

npm 官方对这件事的原话是：npm 由三个不同的东西组成——the website、the Command Line Interface (CLI)、the registry。翻译成人话：

你敲一条命令，三个身份是这样串起来的：

没有它的年代，人是这么干活的

要讲清「它解决什么问题」，最省事的办法是想象它不存在。假设你要用别人写的一个图片压缩库：

• 你得先找到这个库的网站或代码托管页（当年是 Google 搜、翻博客）；
• 把它的压缩包下下来，手动解压，放进项目的某个文件夹；
• 然后发现它自己也依赖别的库——再去把那几个下下来、解压、放进去；
• 那几个库又各自依赖更小的库，如此递归三到五层，全程手工；
• 两个库都要求同一个底层库，但要求的版本不一样——到这里基本就卡死了；
• 终于跑通了，把整个文件夹拷给同事，他那边报错，因为你的系统和你拷的库不匹配；
• 半年后你想升级其中一个库，得把上面这套再走一遍。

npm（以及所有包管理器）解决的正是这一串：把「我这个项目依赖哪些别人的代码、分别要哪个版本」写进一份机器能读的清单，然后自动递归地把它们取回来、摆到正确的位置、并在换一台机器时复现同样的结果。这句话里的每一段，后面都对应一节。

最容易混的一组：仓库是服务，npm 是客户端

日常说话里，这三个身份被混得最狠的是后两个。一个类比可以帮你固定住它们的关系：

02包管理管的不是「包」，是「依赖的依赖」

先花一分钟把「依赖」这个词固定住

依赖（dependency）在这里的意思非常朴素：你这个项目要用别人已经写好的代码。你写十行代码去调用一个别人写好、经过几万人用过的库，那这个库就是你的一个依赖。

而「包」（package）是 npm 里承载依赖的单位：一个有名字、有版本号、并且一定包含一个 package.json 文件的文件夹（发布时被打成一个压缩包）。npm 官方文档对「包」的定义就是这么一句——必须有 package.json 才能被发布到仓库里。

你只写了 15 个，机器装出来 51 个

真实项目里，几乎没有哪个包是「自己一个人就能干活」的。它也要用别人写的东西，于是产生一层层的传递依赖（transitive dependency，意思是「不是你要的，是你要的东西要的」）。

这件事的量级值得亲手看一次。我写了一段脚本，去公共仓库把每个包自己声明的依赖递归走了一遍，把整棵树数了出来（复核方法在 §15）：

这张表里有三个反直觉的地方，每个都值得停一下：

• express 的 28 变成了 63。你只说了「我要 express」，实际到手的是一个 63 个包的集合。这些多出来的包你一个都不用认识，但它们会跑在你的机器上（这一点在 §10 会变成一件严肃的事）。
• next 的「12 个」里有 179.5 MiB，其中 176.2 MiB 是 next 自己。包的数量少，不代表占的地方小。看体积得单独看。
• next 和 vite 的「含可选」列大得离谱（1129 MiB / 356.8 MiB）。这不是笔误：它们把 Windows、macOS、Linux 以及各种 CPU 架构的预编译二进制（意思是这些文件已经编译好、能直接在对应系统上运行）全列进来了，靠 os / cpu 两个字段让你机器上只装匹配的那一个。这是「依赖树」与「你磁盘上实际有什么」之间最大的一处差异。

为什么这件事不能被「手动管」替代

有人会想：既然只是「下几个文件」，我为什么不自己下、自己放？因为真正的难点不在「下」，在对齐：63 个包各自声明了自己能接受的版本范围，要让它们同时成立，是一个约束求解问题。当两个人分别更新了不同的依赖，或者你半年后重装一次，这个解会变——

什么场景该用它

只要一个项目里出现了 JavaScript 代码、并且它要用到别人写的库，npm 就适用。它的覆盖面比「做网站」大得多：

什么时候不该用它

03装 npm：它其实是跟着 Node 一起来的

你不需要单独装 npm

npm 是随 Node.js 一起发下来的。Node.js 是让 JavaScript 能脱离浏览器、直接在你电脑上运行的那个程序——安装它的同时，npm 就被放在同一个目录里了。npm 官方文档的原话是：When you install Node.js, npm is automatically installed.（装了 Node.js，npm 就自动装好了。）

所以要做的只有一件事：确认你装过 Node，然后看它带来了哪个 npm。你已经在 §00 敲过 node -v 和 npm -v 了。

第一个反直觉的地方：Node 自带的 npm 不是最新的

截至 2026-09-23，各条 Node 线自带的 npm 版本是这样（数据来自 Node 官方发布清单，每个版本的元数据里就写着它捆绑的 npm 版本）：

也就是说：截至今天，npm 12 还没有随任何一条 Node 线发布。你装最新 Node 拿到的仍然是 11.x。这不奇怪——npm 是独立发版的，Node 只会在某个时间点把当时的 npm 版本固定进去。这条事实也说明：「我的 npm 版本」是一个需要你自己确认的东西，不是一个跟着 Node 自动最新的东西。

要不要升级，怎么升

先明确一点：如果项目现在跑得动，不升级是完全正当的选择。npm 12 带来了一处会影响安装结果的默认行为改动（§10），升上去之前值得先知道那是什么。

要升级的话就一条命令：

npm install -g npm@latest   # -g = global，装到全局，而不是当前项目
npm -v                     # 确认升上去了

国内网络下常见的一步：换一个镜像源

默认情况下，所有包都从官方仓库 https://registry.npmjs.org/ 取。国内直连它经常很慢，于是有一份同步过来的副本（业内叫「镜像」）可以换：

npm config get registry    # 先看现在指向哪：默认会打印 https://registry.npmjs.org/
npm config set registry https://registry.npmmirror.com   # 换成国内镜像

这条设置会被写进你的用户级配置文件 ~/.npmrc（一个纯文本的「配置清单」文件，npm 启动时读它）。npm 的配置有明确优先级：命令行参数 > 环境变量 > 项目里的 .npmrc > 用户级的 ~/.npmrc > 全局的。也就是说，项目目录里那个 .npmrc 会覆盖你个人的设置——团队项目里它常被用来统一源。

04敲下 npm install 之后，机器按什么顺序干活

六个步骤，按发生顺序

为什么第一次慢、第二次快

除了第 5 步的下载，其余每一步都在本地。而下载这一步只在第一次或者缓存被清掉时才真的跑网络：第二次装同一个包，npm 直接从缓存解包。这就是「第一次装了三分钟、删掉 node_modules 再装只要二十秒」的原因。

知道了这一点，两条命令就有用了：

npm config get cache          # 缓存放在哪（默认 ~/.npm）
npm ci --prefer-offline       # 优先用缓存，缓存里没有再联网
npm ci --offline              # 完全不联网：缓存里缺任何东西就直接失败

官方对 --offline 的说明是「强制离线模式：安装期间不做任何网络请求」。它能用是一个很强的信号——说明这个项目之前的依赖都是同一台机器上装的。反过来，在刚拿到的新机器上敲 --offline 一定失败。

那几行输出到底在说什么

added 63 packages, and audited 64 packages in 3s

found 0 vulnerabilities

顺带说清三个长得很像的命令

npx 和「全局安装」的区别值得单独记一句：npm install -g 包名 是把包装进一个全局位置并一直留着（所有项目都能用，但也会一直留着）；npx 是把包放进缓存里执行一次。不确定要不要长期留着的工具，用 npx。（从 npm 7 起，npx 本身就是 npm exec 的一个更简短的入口。）

05最小例子：从空目录到「换台机器也一样」

这一节是一条可以完整照抄的路。它专门设计成能让你亲眼看到「删掉重装会变、按锁文件装不会变」——这是整篇里最值得花十分钟亲手做一次的实验。

第 0 步：建一个空目录，起一个项目

mkdir npm-demo
cd npm-demo
npm init -y      # -y = 所有问题都用默认答案，生成一个 package.json
cat package.json  # Windows PowerShell 上换成：type package.json

你会看到一个很短的文件，里面有 "name"、"version"、"scripts" 之类的字段。这就是你的采购清单，现在是空的。

第 1 步：装第一个依赖，看它带来了什么

npm install express
cat package.json       # 多了一行 "dependencies"
npm ls --depth=0       # 只列你亲自要的：这里只有 express
npm ls --all           # 整棵树：63 个名字

清单上只多了一行，磁盘上多了 63 个包目录。这一处反差，就是「包管理」三个字的重量所在。

第 2 步：做一个对照实验——删掉锁文件重装

先看看那个自动出现的锁文件长什么样：

ls                     # 除 node_modules 外，多了一个 package-lock.json
head -40 package-lock.json

里面最值得看的是 "lockfileVersion"（格式版本号）和下面每个包的三个字段：version（确切版本）、resolved（从哪个地址下载的）、integrity（校验值）。现在做这个实验：

rm -rf node_modules package-lock.json   # Windows：rmdir /s /q node_modules && del package-lock.json
npm install                             # 没有锁文件，它要重新算一遍「范围」里最新的是什么

如果这中间有过新版本发布，这次装到的版本就和你上次装的不一样——而你什么都没改。这就是「不能只靠 package.json」的现场演示。

第 3 步：换成按锁文件装

rm -rf node_modules     # 注意：这次不删 package-lock.json
npm ci                  # 严格照锁文件装，一个版本都不许协商

npm ci 的承诺是：只要锁文件没变、仓库里那些版本还在，装出来的东西就一定和上次一样。这条承诺是整个生态能协作的基础——服务器、同事的电脑、CI 机器，靠的都是它。

第 4 步：加一个「只在开发时用」的依赖，再加一条自己的命令

npm install --save-dev prettier          # 写进 devDependencies 而不是 dependencies
npm pkg set scripts.check="prettier --check ."   # 往 package.json 的 scripts 里加一条
npm run check                             # 跑这条脚本

--save-dev 的效果是把它记进 devDependencies 而不是 dependencies。这个区分的意义在 §06，但那句「npm run 名字 就是执行 scripts 里对应的那行命令」现在就可以记住——AI 给你的 npm run dev、npm run build，全都是这个机制，没有例外。

这个例子里每条命令各证明了什么

06package.json：哪个字段是给谁看的

这个文件里字段很多，但绝大多数你一辈子不用改。最有价值的一栏是「谁读它」——同一份文件里，有的字段是给 npm 自己看的，有的是给别的工具看的，有的是给人类看的。

dependencies 与 devDependencies：最容易混的一对

这一对的区别只有一个问题：「这东西在项目真正跑起来的时候，还需要吗？」

peerDependencies：ERESOLVE 报错的源头

这个字段的用途有点绕，但值得懂，因为新手遇到的第一大报错（ERESOLVE）几乎都从这里来。

它要表达的是：「我是一个插件，我需要宿主程序是某个版本，但我不把宿主程序打包进来。」典型例子是一个 React 组件库——它必须和你的 React 配合工作，但绝不能自带一份 React（否则你的页面里会有两个 React，直接崩）。所以它声明 "peerDependencies": {"react": "^19.0.0"}：「我要求你（宿主项目）提供这个版本的 React。」

历史上这里有个重要分界：npm 7 之前（3~6），peerDependencies 不会自动安装，只是不匹配时给个警告；从 npm 7 起（2020-10 发布，随 Node 15 分发），它会被自动安装。好处是少了一类「你还得自己再装一次」的坑；代价是两个插件要求不同版本的主程序时，npm 会直接报错而不是警告——这就是 ERESOLVE。

optionalDependencies：那 1129 MiB 是怎么来的

回头看 §02 那张表里 next 的 1129 MiB。它是这么产生的：next 把「Windows 版二进制」「macOS 版二进制」「Linux 各架构版二进制」全都列为可选依赖，同时用另外两个字段限制它们各自只在对应平台上生效：

{
  "os":  ["darwin", "linux"],   # 允许在这些操作系统上安装
  "cpu": ["x64", "arm64"]       # 允许在这些 CPU 架构上安装
}

于是：你的机器上只会装匹配的那一个（约 90~100 MiB），其余的在解析阶段就被排除了。这也是「别人发的 node_modules 拷给你用不了」的技术原因——里面装的二进制是给他那台机器编的。

workspaces：一个仓库里放多个项目

当你有「网站 + 共用组件库 + 后台服务」放在同一个仓库里（业内叫 monorepo，mono = 单一，repo = 仓库），用 workspaces 声明它们，npm 安装时会自动把子包互相链接起来，不需要你手工去建链接。官方对这个功能的描述是「自动化了链接过程，免去手工使用 npm link」。它从 npm 7 起提供。

顺带提一句 packageManager 字段：它写的是「这个项目应该用哪个包管理器、哪个版本」，配套的工具叫 Corepack。但要注意现状：Corepack 至今仍是实验性功能，而且从 Node 25 起已经不再随 Node 分发（Node 24 里还有）。所以它不是一个能指望的强制手段，团队约定仍然主要靠文档和 CI。

不想手改 JSON 的时候：npm pkg set

npm pkg set scripts.dev="next dev"              # 加一条脚本
npm pkg set private=true                        # 防止被误发布
npm pkg get scripts                             # 读出来看看

这里的 package.json 是 JSON 格式（一种纯文本的数据格式：用大括号和引号描述结构，机器一眼能读，人也不难读）。它用点号表示嵌套层级，写回时会沿用你原来的缩进格式。对不熟 JSON 语法的人来说，这比手改文件安全——少打一个逗号或引号，整个项目就跑不起来了。

07^1.2.3 到底允许装哪个版本

这一节是全文最值得逐行读的一节。因为几乎所有「昨天还好好的，今天就装不上了」的事故，根源都在这几个符号上。

先看版本号本身：三段数字各是什么

4.18.2 这样的版本号，三段数字的含义由一套叫语义化版本（semantic versioning，简称 semver）的约定规定：

这套约定是 2011 年由 Tom Preston-Werner 提出的，规范文本在 semver.org，npm 用的具体实现是 github.com/npm/node-semver。关键在于：它是一个「约定」，不是技术强制。包作者是否严格遵守，你无法验证——这解释了为什么下面那些符号只是「大概率安全」，而不是保证。

最要紧的一张表：写在 package.json 里的符号允许装什么

0.x 的坑：写着 ^ 却几乎锁死

尖号的规则有一句精确表述：它允许变化的范围，是「最左边那个非零数字」往右。对 1.0.0 以上的版本，最左边非零的是主版本，所以 ^1.2.3 允许变到 1.x 的尽头。但对 0.2.3，最左边非零的是次版本（那个 2），于是：

"^0.2.3"   # 实际只允许 0.2.x —— 从 0.2.3 到 0.3.0 之前

这件事对你有现实影响：很多年轻的工具（尤其是 AI 相关的新项目）都还在 0.x 阶段。你写 ^0.2.3 以为它会自动跟进新功能，实际上它停在 0.2.x。要跟进就得手动改。反过来这也是保护——0.x 阶段的作者按惯例会把次版本当破坏性版本用。

预发布版本不会自己进来

像 1.3.0-beta.1 这种带后缀的版本叫预发布版本（beta 是「测试版」的意思）。规则是：除非你明确写了带预发布后缀的范围，否则它不会被选中。

"^1.2.3"   # 不会装到 1.3.0-beta.1，只会往 1.3.0 正式版走

这条规则的设计意图官方写得很清楚：预发布版本「更新频繁、常常包含破坏性改动」，而且一个包同时存在多组 alpha/beta 序列，谁也不知道你想要哪一组。所以默认排除，只有你显式写出来才算同意了风险。

那我到底该写哪种

08package-lock.json：为什么它比 package.json 更重要

它记的是「上次的解」，不是「你的意图」

官方对这个文件的定义是：它由任何改动 node_modules 或 package.json 的操作自动生成，描述「实际生成出来的那棵树」，使得后续安装无论中间依赖有没有更新，都能生成一模一样的树。每个条目里最关键的三个字段：

官方原话：这个文件应该被提交到 git

npm 文档写得很直接：This file is intended to be committed into source repositories.（这个文件应当被提交进源码仓库。）它列了四个用途，其中最关键的两个：让同事、部署环境、持续集成「保证装到完全相同的依赖」；以及允许你「时间旅行」回之前的状态，而不必把整个 node_modules 也提交进去。

顺带回答一个几乎人人都会问的问题：node_modules 该不该提交？不该。证据是 GitHub 官方维护的 .gitignore 模板里，Node 那一份明确把 node_modules/ 列在「Dependency directories（依赖目录）」下面。提交锁文件，不提交依赖目录——这一条是标准做法，不是风格偏好。

版本号格式的三代

npm install 与 npm ci：五条官方差异

所以选择很简单：日常你在改依赖，用 npm install；只要目标环境需要「和上次一模一样」（服务器、CI、别人拿到你的项目），用 npm ci。本仓的 CI/CD 怎么用 里那条流水线，装依赖那一步就该是 npm ci。

npm config set legacy-peer-deps=true --location=project   # 写进项目 .npmrc，然后提交它

锁文件冲突了怎么办

多人协作时，package-lock.json 是最容易起冲突的文件（几千行、每行都可能变）。处理顺序建议是：

09node_modules：为什么这么大、能不能删、要不要提交

先看它到底有多大

§02 那张表已经给过一次包数量：express 是 63 个包、解包后约 2.1 MiB；eslint 是 75 个包、约 10.8 MiB。这两个数说明「包多」不等于「占地方大」——60 多个小包加起来才 2 MB。真正让 node_modules 胀起来的，是另一类东西：给不同操作系统准备好的预编译文件。

所以「我的 node_modules 有 500 MB 正常吗」的答案是：对现代前端项目来说很正常。它主要由三类东西撑起来——框架自己的代码、各个平台的预编译二进制、以及几十上百个小工具包。

为什么清单上只有 28 个，磁盘上却有 63 个目录

因为 npm 会把依赖树尽量拍平（业内叫 hoisting，直译「往上提」）。官方文档用一个小例子讲清了它的算法：

# 假设依赖关系是 A 需要 B 和 C，B 需要 C，C 需要 D
A
├── B
├── C      # B 要的 C 已经在顶层有了，直接共用，不再装一份
└── D

# 但如果 B 要 D 的 1 版、C 要 D 的 2 版，冲突了：
A
├── B
├── C
│   └── D@2    # 顶层放一个，另一个塞进需要它的包自己的目录里
└── D@1

这就是为什么 node_modules 里既有大量平铺的文件夹，又会在某些包下面再嵌套一层。官方对这个算法的评价是「确定性的」，但也留了一句重要的提醒：如果两个依赖的安装顺序不同，可能产出不同的树。

npm install --install-strategy=linked   # 官方推荐给「包作者」在开发时用来抓幽灵依赖

那它能不能删

能删，而且随时可以删——这正是「提交锁文件、不提交依赖目录」这套做法的前提。删了以后用一条命令重建：

rm -rf node_modules     # Windows：rmdir /s /q node_modules
npm ci                  # 按锁文件重建，结果和删之前一样

四个「看树」的命令

其中 npm explain 是最被低估的一个。AI 给你一个报错、你看到一个从没听过的包名时，用它基本能在一分钟内搞清「它是谁带进来的」。

10装一个包，等于让别人的代码在你电脑上跑

这一节讲的是整个 npm 体系里最需要你真正理解的一件事。它不需要你会写代码，但需要你知道它存在。

机制：安装脚本

包作者可以在自己的 package.json 里写一段在安装时自动执行的命令，叫安装脚本（install script，包括 preinstall、install、postinstall、prepare 这几个名字）。

这个机制本身是必要的、也是善意的：很多包需要在你机器上现场编译（sharp、canvas 这类要处理图片的包，需要按你的系统编译一份二进制），或者下载配套的可执行文件。没有它，这些包根本装不上。

但它的另一面是：你在第 1 步敲的那条 npm install，会让几十个你从未听说过的包的作者，在你电脑上执行他们写的命令。而且这些命令是在你的用户权限下跑的——能读你的文件、能联网。

2025 年那场事故：Shai-Hulud 蠕虫

这不是理论风险。下面是按时间排的事件（出处见 §15）：

npm 12 具体改了什么，你会遇到什么

行为变化用一句话概括：以前是「默认全跑」，现在是「默认不跑，你逐个批准」。落到操作上：

npm install                          # 装依赖，但依赖的安装脚本会被跳过
npm install-scripts ls               # 看哪些包有脚本、哪些被跳过了
npm install-scripts approve sharp    # 批准某个包
npm rebuild                          # 让刚批准的脚本真正跑一次

批准的结果会被记在项目的 package.json 里（一个叫 allowScripts 的策略），所以它可以跟代码一起提交、被团队和 CI 共用——这比每个人在自己机器上盲点「同意」要靠谱得多。

作为「装包的人」，你现在能做的五件事

npm install --before=2026-09-20   # 只装 2026-09-20 之前发布的版本

11报错对照表：看到这行字，实际发生了什么

npm 的报错都以 npm error code XXX 的形式给出错误码。下面是你会撞到的几类，以及它们真正在说什么。

12该不该换成 pnpm / yarn / bun

你会在很多文章里看到「pnpm 更快、更省磁盘」之类的说法。它们大体上是真的，但换包管理器是一个团队级决定，不是性能优化。先看它们到底差在哪。

什么时候值得换

• 你机器上同时有好几个项目，磁盘吃紧。pnpm 的全局仓库模型在这里收益最明显——同一个包在十个项目里只存一份。
• 你在维护一个多包仓库（monorepo）。pnpm 与 yarn 在这方面做得更早、更成熟。
• 你被幽灵依赖坑过一次，想从机制上避免它。

什么时候别换

13一页纸：以后回来只翻这一节

命令速查

五条判断，不用记细节也能做对

14名词速查：别把它们当成什么用

下面这些词在 AI 给的说明和报错里高频出现。第三列是这张表真正的价值——它告诉你这个词最容易被误当成什么。

15来源与证据边界

这篇里凡涉及「现在是多少」「现在是哪个版本」「默认行为是什么」的判断，核对日期统一为 2026-09-23。下面是出处，按类别分组。

官方文档（一手）

• docs.npmjs.com — About npm — npm 由 website / CLI / registry 三个组件组成、「世界上最大的软件仓库」这两句的出处
• docs.npmjs.com — Logos and Usage（用词政策） — 「npm 不应被当作缩写使用或解释」这句原文的出处（§01）
• docs.npmjs.com — npm ci — npm ci 与 npm install 的五条差异、install-strategy 四种布局（§08、§09）
• docs.npmjs.com — npm install — 依赖树的拍平算法与其「确定性但可能因顺序而异」的说明（§09）
• docs.npmjs.com — package-lock.json — 「应当提交进源码仓库」的原话、lockfileVersion 1/2/3 的官方对应关系、隐藏锁文件（§08）
• docs.npmjs.com — package.json 参考 — 各字段含义、os/cpu/libc、peerDependencies 在 npm 7 起自动安装、workspaces（§06）
• docs.npmjs.com — .npmrc 与 config 参考 — 配置优先级、offline/omit/before/allow-scripts/legacy-peer-deps/force 的官方描述（§03、§04、§06、§10）
• docs.npmjs.com — npm install-scripts — npm 12 的脚本批准机制与四种子命令（§10）
• docs.npmjs.com — scripts — 生命周期脚本的执行顺序，含「preinstall 在依赖被取下来之前运行」「npm ci 会先清空 node_modules」（§04、§10）
• docs.npmjs.com — npm audit · npm ls · npm explain · npm outdated · npm dedupe · npm prune — §09、§11、§13 那些命令语义的出处
• docs.npmjs.com — npx 与 npm prefix — npx 的行为、npm 向上查找项目根的依据（§04）
• docs.npmjs.com — Trusted publishing — OIDC 可信发布、版本要求（CLI ≥ 11.5.1、Node ≥ 22.14.0）、支持的 CI 平台（§10）
• semver.org 与 github.com/npm/node-semver（README——仓库首页那份说明文件——的 Ranges 一节）— §07 那张表的每一条规则，含 0.x 与预发布版本的特殊处理
• github/gitignore 的 Node 模板 — node_modules/ 被列为「依赖目录」（§08）

发布说明与公告（版本与默认行为的依据）

• npm CLI v12.0.0 发布说明（2026-07-08） — 依赖安装脚本默认被阻断、allow-git/allow-remote 默认 none、npm shrinkwrap 移除、Node 版本要求
• npm CLI v12.1.0 发布说明（2026-09-21/22） — 本文的版本锚点
• npm v7 changelog（2020-10-12） — peerDependencies 改为默认安装、workspaces 第一阶段（§06、§09）
• GitHub changelog（2026-05-22） — 暂存发布正式可用、四种安装来源白名单开关（§10）
• GitHub 安全博客（2025-09-22） — 「2025-09-14 收到 Shai-Hulud 通知」「移除 500 多个被投毒的包」、以及发布侧加固路线（2FA、七天有效的细粒度令牌、可信发布）
• GitHub 公告（2020-03-16） — GitHub 收购 npm，并留下了一个历史横截面数字：「130 万个包、每月 750 亿次下载」（§15 用来对照今天的量级）
• npm 官方博客（2014-09-11） — 「npm 由 Isaac Z. Schlueter 于 2009 年创建」「2014 年 1 月底成立 npm, Inc.」「2014-02-04 起由 npm, Inc. 托管 registry」
• Node.js 官方博客（2011-05-01） — npm 1.0 发布
• nodejs/node PR #61207 — Corepack 从 Node 25 起不再随 Node 分发的决定（§06、§12）。PR 是「合并请求」，也就是一次代码改动的提案与讨论记录

本文自己做的核对（不是转述）

正文里有几处数字是本文当天亲手从一手接口取的，你可以用同样的方式复现：

已知的分歧、薄弱处与时效

时效提示：这篇属于「演进型」——机制部分（依赖树怎么解、锁文件为什么存在、为什么会有幽灵依赖）不容易过时，但版本号、默认行为、安全机制的状态天天在变。本文校对日期 2026-09-23；其中提到 npm 12 的默认行为改动就在两个多月前，是本文里最「新」也最容易过期的一段。动手前请以你机器上 npm --version 和官方文档为准。

99一句话总结