前端工程化（五）：依赖版本与可复现安装

package.json 和 lockfile 是两层信息

package.json 是项目的依赖声明和工作入口。它包含项目名称、脚本、直接依赖、开发依赖、包管理器版本等信息，表达的是“项目需要什么”。例如 my-world 的 package.json 同时声明了 Next.js、React、Payload、TypeScript 等直接依赖，以及 build、lint 等脚本。

package-lock.json 则记录包管理器实际解析出的完整依赖树。它不仅记录顶层依赖，还包括传递依赖、具体版本、下载地址、完整性校验和依赖关系。它表达的是“这次安装实际拿到了什么”。

因此，两者应该同时保留：package.json 便于人理解和修改，lockfile 让团队、CI 和不同机器尽量安装同一组依赖。

semver 决定版本可以怎样变化

版本范围不是“当前一定安装的版本”，而是允许解析器选择的范围。例如：

{
  "next": "^16.2.11",
  "pg": "8.20.0"
}

^16.2.11 通常允许在不跨越 17.0.0 的前提下更新次版本和补丁版本；8.20.0 是精确版本，不接受版本范围内的自动升级。

范围版本适合遵循同一主版本兼容承诺的依赖，精确版本则适合对兼容性、数据库驱动行为或升级风险更敏感的依赖。但无论 package.json 写的是范围还是精确版本，最终实际安装结果仍应由 lockfile 固定。

直接依赖和传递依赖都需要管理

直接依赖是项目在 package.json 中明确声明并直接使用的包。传递依赖是这些直接依赖继续依赖的包，项目可能没有在源码中直接引用它，却仍然会受到它的版本和行为影响。

传递依赖也可能升级，也可能被多个直接依赖共同使用，还可能出现重复版本、peer dependency 冲突或安全漏洞。因此 lockfile 需要记录完整依赖树，而不是只记录 package.json 顶层列出的包。

npm install 和 npm ci 的区别

npm install 主要用于日常开发。它会结合 package.json 和现有 lockfile 安装依赖；当依赖声明发生变化时，也可能重新解析并更新 lockfile。

npm ci 更适合 CI 环境。它要求 package.json 和 lockfile 已经一致，通常会清理现有 node_modules，然后严格按照 lockfile 做一次干净安装。如果两者不一致，命令会直接失败，而不是悄悄生成一份新的依赖结果。

这使 npm ci 具备更强的可复现性，但要注意：可复现安装不等于项目运行时一定正确。安装成功之后仍然需要通过类型检查、lint、测试和构建验证代码行为。

为什么不能随意删除 lockfile

删除 lockfile 会触发依赖重新解析。即使 package.json 没有改动，范围版本也可能解析到新的次版本或补丁版本，传递依赖也可能发生变化。

这会带来几类问题：本地和 CI 安装出不同结果，团队成员之间出现难以复现的幽灵故障，依赖升级没有清晰的 diff，出现问题时也很难判断究竟是哪一个传递依赖变化造成的。

如果确实要升级依赖，应通过明确的版本修改或受控升级命令更新 lockfile，并审查差异，而不是用删除锁文件的方式“重新开始”。

packageManager 固定安装工具版本

my-world/package.json 当前声明：

{
  "packageManager": "npm@10.8.2"
}

这个字段约束的是“使用什么工具、哪个版本执行安装”；package-lock.json 约束的是“最终解析并安装哪些依赖版本”。前者解决包管理器行为差异，后者解决依赖结果差异。

如果团队成员使用不同 npm 版本，lockfile 的处理方式、依赖解析细节或脚本行为可能出现差异。固定包管理器版本不能替代 lockfile，lockfile 也不能替代工具版本约束，两者需要配合。

缓存加快安装，但不负责决定版本

npm 或 pnpm 缓存可以保存已经下载过的包内容。CI 再次安装相同版本时，可以从本机或远程缓存读取，减少重复网络请求，从而缩短安装时间。

缓存解决的是“如何更快拿到包”，lockfile 解决的是“应该拿哪些包”。缓存失效、迁移机器或切换 CI 节点时，安装仍然应该能够依靠 lockfile 正确完成。因此，启用依赖缓存不能成为删除 lockfile 的理由。

依赖升级如何控制风险

升级 Next.js、React 或其他关键依赖时，我会按以下顺序执行：

1. 明确升级是为了解决漏洞、获得新能力，还是修复兼容性问题。
2. 确认目标版本、发布稳定性、breaking change 和 peer dependency 要求。
3. 在独立分支执行升级，审查 package-lock.json 的变化范围。
4. 检查直接依赖、传递依赖和重复版本是否发生异常变化。
5. 运行类型检查、lint、自动化测试和生产构建。
6. 通过验证后再合并，并保留回滚版本和失败证据。

这个过程的重点不是阻止所有升级，而是让每次升级都有明确动机、可审查 diff、可重复验证和可回滚路径。

my-world 的真实依赖事实

当前项目使用 npm@10.8.2，package-lock.json 使用 lockfileVersion 3。依赖声明中同时存在范围版本和精确版本，例如 next: ^16.2.11、pg: 8.20.0。lockfile 中可以继续追踪每个包的具体版本、resolved 地址、integrity 校验、传递依赖和 peer dependency 信息。

这些事实可以支持面试中的项目举证，但不能把“存在 lockfile”直接说成“项目已经没有依赖风险”。依赖风险仍需要通过升级审查、安装验证、测试和构建门禁持续控制。