Bundler frozen 模式 — Gemfile.lock 将被修改

症状

本篇调试指南针对“Bundler frozen 模式 — Gemfile.lock 将被修改”。内容涵盖可观察的症状、可复现的诊断路径、根本原因、具体修复方式，以及如何验证修复并防止回归。

可观察到的症状包括：

• bundle install 失败并提示 “you are trying to install in deployment mode … would have changed”
• CI 失败而本地安装正常
• 错误提示 Gemfile.lock 将被修改

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

bundle install && git add Gemfile.lock && git commit -m "update lockfile"

在本地更新并提交 lock，使部署模式能找到一致的锁文件。

步骤 2

bundle config list | grep -i frozen

若 frozen 为 true，CI 禁止任何 lockfile 改动；正确做法是提交正确的 lock，而非关闭 frozen。

常见诱因（按出现频率排序）：

• Gemfile 与 Gemfile.lock 不同步（新增 gem 未更新 lock）
• lockfile 缺失或未提交，部署模式无从校验
• 设置了 bundle config frozen/deployment，禁止写入 lockfile

根因

在 frozen/deployment 模式下，Bundler 拒绝修改 Gemfile.lock。若 Gemfile 与 lock 不一致，或 lock 缺失，安装无法进行，因为遵循 lock 就意味着必须修改它。

修复

在本地以非 frozen 模式运行 bundle install 重新生成 Gemfile.lock 并提交，同时让部署保持 frozen，以保证 CI 可复现。

注意：为强行部署而关闭 frozen 会产生不可复现的构建；不可仅为通过 CI 就关闭。

# local: regenerate and commit the lock
bundle install
bundle lock --update
git add Gemfile.lock && git commit -m "sync Gemfile.lock"

# CI/deploy: keep frozen to guarantee reproducibility
bundle config set --local deployment true
bundle config set --local frozen true
bundle install --frozen

验证

在干净检出下运行 bundle install –frozen，确认成功且 lock 未变化；断言 bundle check 通过。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。