第4章 依赖版本锁定与语义化版本控制
你有没有遇到过这种场景：项目今天还能正常构建，第二天一跑就崩了，查了半天发现是一个小依赖偷偷升了个小版本？
嗯，这就是经典的“依赖地狱”。我早期带团队时就吃过这个亏，一个测试环境好好的，上了预发就报错，最后定位到是 lodash 的一个补丁版本引入了行为变化。从那以后，我对版本锁定和语义化版本控制就特别上心。
4.1 为什么需要版本锁定？
说白了，版本锁定就是把你项目里每一个依赖的版本号“钉死”。你想想看，你的项目依赖 A，A 又依赖 B 和 C，这棵依赖树只要有一个节点不受控，整个构建就可能翻车。
我见过不少团队，package.json 里写的是 "^1.2.0"，觉得差不多就行。结果半年后 CI 突然红了，因为某个间接依赖发布了 breaking change。这时候你再回头查，根本记不清当初锁定的是哪个版本。
核心目标：确保每次构建使用完全相同的依赖版本，实现可重复构建。
4.2 语义化版本控制（SemVer）
要锁版本，先得懂版本号怎么来的。语义化版本控制（SemVer）是目前最通用的规范，格式是 MAJOR.MINOR.PATCH。
| 位置 | 名称 | 含义 | 示例 |
|---|---|---|---|
| MAJOR | 主版本号 | 做了不兼容的 API 变更 | 2.0.0 → 3.0.0 |
| MINOR | 次版本号 | 新增了向下兼容的功能 | 2.1.0 → 2.2.0 |
| PATCH | 修订号 | 做了向下兼容的 Bug 修复 | 2.1.0 → 2.1.1 |
我个人习惯在项目中严格要求依赖发布方遵守 SemVer，否则版本号就失去了意义。你想想看，一个连 SemVer 都不遵守的库，你敢放心用吗？
4.3 版本锁定的三种策略
光懂 SemVer 还不够，你还得知道怎么锁。我总结下来，主流的锁定策略有三种：
- 精确锁定：直接写死版本号，比如
"1.2.3"。最严格，但容易错过补丁更新。 - 范围锁定：用
^或~允许一定范围内的自动升级。^1.2.3允许升级 MINOR 和 PATCH，~1.2.3只允许 PATCH。 - Lock 文件锁定：由包管理器自动生成（如
package-lock.json、yarn.lock），锁定整个依赖树的精确版本。
| 策略 | 可靠性 | 灵活性 | 推荐场景 |
|---|---|---|---|
| 精确锁定 | 高 | 低 | 核心依赖、生产环境 |
| 范围锁定 | 中 | 中 | 开发环境、非核心库 |
| Lock 文件 | 高 | 高 | 所有场景（强烈推荐） |
我在项目中推荐“组合拳”：package.json 里用范围锁定保持可维护性，同时将 package-lock.json 纳入版本控制，CI 中严格基于 lock 文件安装依赖。这样既灵活又可靠。
4.4 CI 中如何落地版本锁定？
理论讲完了，咱们看看实际在 CI 里怎么干。我以 Node.js 生态为例，其他语言思路类似。
首先，package-lock.json 或 yarn.lock 必须提交到 Git 仓库。这是前提，没有这个文件，后面的自动化无从谈起。
提示：在 .gitignore 中永远不要忽略 lock 文件！很多新人觉得 lock 文件是自动生成的没必要提交，这是个大坑。
# .gitignore 反例（错误）
package-lock.json # ❌ 不要这样做！
# .gitignore 正例（正确）
# 不要忽略任何 lock 文件
在 CI 脚本中，使用 npm ci 而不是 npm install。npm ci 会严格按照 lock 文件安装依赖，如果 lock 文件与 package.json 不一致，它会直接报错，而不是悄悄修改 lock 文件。
# 在 GitHub Actions 中示例
jobs:
build:
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 18
cache: 'npm'
- run: npm ci # 严格基于 lock 文件安装
- run: npm test我曾经在某个项目中，团队有人用 npm install 在本地安装，结果 lock 文件被意外修改了，CI 一直报错。后来强制改用 npm ci，这种问题再没出现过。
4.5 避坑指南
⚠️ 我曾经踩过的坑：
- Lock 文件冲突不解决就合并——多个分支修改了依赖，合并时 lock 文件冲突，有人直接删掉 lock 文件重新生成，导致引入了未经验证的版本组合。正确做法是手动解决冲突，然后重新运行
npm install更新 lock 文件。 - 生产环境与 CI 使用不同的安装命令——本地用
yarn，CI 用npm，两个包管理器的解析算法不同，lock 文件不通用。统一包管理器。 - 忽略 SemVer 中的预发布标签——
1.0.0-alpha.1这种版本在语义化版本中不受信任，不要在生产依赖中锁定预发布版。
依赖版本锁定不是银弹，但它是最基础、最有效的防线。
把版本锁定和语义化版本控制结合起来，你的 CI 构建会稳如磐石。别等到线上出问题了，才想起来去查版本号。