锁文件

你可能会说：

• “我本地能构建，为什么部署平台上构建失败？”
• “package-lock.json 这么长，能删掉吗？”

它是什么

package.json 里常写的是版本范围（比如 ^7.3.5，意思是 7.x 的任意新版本）。锁文件记下的是这一次实际装上的确切版本，包括所有间接依赖。

部署平台构建时通常用 npm ci 这类命令，严格按锁文件安装；锁文件和 package.json 对不上，就直接失败。所以锁文件必须提交进仓库，并且和依赖的改动一起提交。

不同版本的包管理器生成的锁文件，格式和内容可能有差异。本地用新版本生成、线上用旧版本安装，就可能出现"本地好好的，线上构建失败"。

打个比方

像药方上精确到克的剂量：只写"甘草适量"，每个药房抓出来都不一样；写清"甘草 6 克、产地某某"，才能保证每次抓的药一致。

在这个网站里

这个网站的锁文件，必须用 npm 10 生成（npx npm@10 install）：Cloudflare 的构建环境用 npm 10 执行 npm ci，而本地 npm 11 生成的锁文件缺了几个可选依赖的条目，让线上构建直接失败（第 10 课）。

容易搞混的地方

你可以这样告诉 AI

接下来去哪

先知道

• 依赖——项目运行需要、但不是你自己写的代码：框架、工具库，以及它们各自又依赖的一长串包。

接着看

• 包管理器——负责下载、安装、升级依赖的工具，也负责生成和读取锁文件。
• 运行环境版本——运行你代码的那个程序（比如 Node.js）的版本。版本不对，有些依赖根本跑不起来。

在这些课里出现

• 第 10 课 · 依赖、锁文件与运行环境