版本锁定实战：从 `git tag` 到 `package-lock.json` 的完整闭环

我维护一个内部 CLI 工具，最近被一个诡异 bug 折腾了两天：同事在 CI 上拉下来的依赖版本，和我本地完全对不上。排查到最后，发现是 package.json 里写的是 ^1.2.0，而 npm 在两周后悄悄发布了 1.3.0，行为有破坏性变更。这让我下定决心，把"版本 pin"这件事从口头约定变成硬性纪律。

为什么 `^` 和 `~` 是定时炸弹

先看一个最常见的坑。你打开 package.json，大概率看到这样的依赖：

json 复制代码

{
  "dependencies": {
    "lodash": "^4.17.21",
    "react": "~18.2.0"
  }
}

^4.17.21 允许 npm 安装 4.x.x 内所有新版本，~18.2.0 只允许 18.2.x 补丁。听起来很合理？但问题在于：补丁版本也可能引入行为变化 。我遇到过 chalk 从 4.1.2 升到 4.1.3 后，ANSI 转义码输出多了一个空格，导致日志解析脚本直接崩掉。

真正可靠的锁版本方式，是让 package.json 里写死具体版本，不带任何前缀：

json 复制代码

{
  "dependencies": {
    "lodash": "4.17.21",
    "react": "18.2.0"
  }
}

但这里有个边界情况：如果你直接手改 package.json，而不重新生成锁文件，npm 会报 ERESOLVE 错误。正确流程是：

bash 复制代码

# 先删除旧锁文件（谨慎操作，确保 git 工作区干净）
rm package-lock.json
# 重新安装，生成新的锁文件
npm install --save-exact lodash@4.17.21

注意 --save-exact 这个参数，它会让 npm 自动写入精确版本，而不是 ^ 前缀。我建议在团队 .npmrc 里加上：

ini 复制代码

save-exact=true

这样以后每次 npm install <pkg> 都默认锁死版本，从源头堵住漏洞。

用 `git tag` 给发布版本打锚点

锁依赖只是第一步。对于我们自己发布的库，git tag 是版本 pin 的另一种形态。我通常用语义化版本 + 前缀 v，比如 v1.2.0。但 tag 也有坑：tag 指向的 commit 是可移动的。

我吃过一次亏：某次热修复，我直接在 master 上提交，然后打了 v1.2.1 的 tag。结果发现修复不完整，又补了一个 commit，然后删掉旧 tag 重新打。虽然本地没问题，但同事的 CI 已经拉过旧 tag，缓存里还是旧代码。

正确的做法是：tag 一旦发布，就不可变 。如果发现 bug，就基于该 tag 开一个 hotfix/1.2.x 分支，修完打 v1.2.2，而不是移动 v1.2.1。

创建不可变 tag 的命令：

bash 复制代码

# 打 tag，并附上签名（可选）
git tag -a v1.2.0 -m "Release v1.2.0"
# 推送 tag 到远程，注意 --tags 会推送所有本地 tag
git push origin v1.2.0

这里有个边界情况：如果你误打了一个 tag，想删除，必须同时删除本地和远程 ，否则下次 git fetch --tags 又会拉回来：

bash 复制代码

git tag -d v1.2.0
git push origin :refs/tags/v1.2.0

锁文件是团队的宪法，必须提交进仓库

我见过很多团队把 package-lock.json 或 yarn.lock 加进 .gitignore，理由是"文件太大，冲突太多"。这是最危险的操作。锁文件的作用是记录依赖树的精确哈希 ，它保证了任何人在任何时间 npm ci，拿到的依赖完全一致。

正确的流程是：

锁文件必须提交进 Git 仓库。
CI 里用 npm ci 而不是 npm install。npm ci 会严格按锁文件安装，如果锁文件和 package.json 不一致，直接报错退出。
升级依赖时，用 npm update <pkg> 或 npm install <pkg>@<new-version>，它会自动更新锁文件。

一个实际失败的场景：某次我在 CI 上跑 npm install，因为网络抖动，npm 解析了 package.json 里的 ^ 范围，拉了一个新版本，锁文件没变。结果构建产物和本地不一致。换成 npm ci 后，这个问题彻底消失。

PowerShell 用户（Windows 环境）注意，npm ci 在 Windows 上同样有效，但如果你用 yarn，对应命令是 yarn install --frozen-lockfile：

powershell 复制代码

# Windows PowerShell 下，强制使用锁文件
yarn install --frozen-lockfile

版本 pin 的终极武器：`overrides` 和 `resolutions`

有时候，你依赖的库 A 内部依赖了库 B，而 B 有安全漏洞。你无法直接改 A 的 package.json，但 npm 提供了 overrides 字段来强制覆盖传递依赖的版本：

json 复制代码

{
  "overrides": {
    "lodash": "4.17.21",
    "chalk": {
      "ansi-styles": "6.2.1"
    }
  }
}

这个字段的坑在于：它必须匹配锁文件里实际的依赖树 。如果 A 依赖的是 lodash@4.17.20，你 override 成 4.17.21，npm 会重新解析整个树。如果 override 的版本和现有依赖不兼容，会报 EOVERRIDE 错误。我建议在 overrides 里写死精确版本，不要用范围。

对于 pnpm 用户，对应的是 pnpm.overrides；yarn 用户则是 resolutions。原理相同，但语法略有差异，记得查对应文档。

一点说明

以上是我在三个项目里踩坑总结出来的实操流程。但版本 pin 没有银弹------比如 monorepo 里的 workspace 依赖，或者某些私有 npm 镜像的缓存策略，都可能让锁文件失效。你遇到过哪些"版本明明 pin 了，但还是跑出不同结果"的场景？欢迎在评论区补充，我特别想听听关于 npm ci 在 CI 缓存目录下行为不一致的案例。

版本锁定实战：从 `git tag` 到 `package-lock.json` 的完整闭环