Ruby 版本迁移：Gem 依赖、Bundler 与运行时弃用项

Ruby 解释器升级常与 Gem 生态、Bundler 解析结果和框架版本耦合。一个应用在本地能够启动，不代表在全新环境能稳定安装，也不代表后台任务和命令行脚本都没有行为差异。较好的迁移方式是固定依赖集合、清理环境、观察警告，并把每个修订与明确的失败样例关联起来。

从版本管理与可执行路径开始

Ruby 版本管理工具可能让终端、测试进程和部署脚本使用不同解释器。升级前后分别记录 ruby、gem 与 bundler 的版本及实际路径，检查项目配置是否指定了目标版本。构建环境应与本地使用同样的声明来源，避免某台机器因为全局默认设置意外选择了旧解释器。把版本输出写入自动化日志，能显著降低排查成本。

用锁定文件控制依赖变量

首次迁移只更换解释器，保留 Gemfile.lock，执行一次全新安装与测试。若安装失败，查看是否由带原生扩展的 Gem、系统头文件或旧版 Bundler 引起。只有在解释器兼容问题解决后，再单独更新依赖并审阅锁定文件变化。框架、数据库适配器、模板引擎和测试工具通常是高影响组件，应安排独立的集成场景验证。

把弃用警告变成代码任务

运行测试与常用命令时收集弃用警告，按调用位置排序处理。警告可能来自应用代码，也可能来自暂未升级的依赖；两种情况需要不同处置。对应用代码，按照推荐替代方式调整并补上回归测试；对依赖代码，记录所用版本和上游状态，在确认没有替代方案前不应隐藏全部警告。尤其留意关键字参数、编码、正则表达式和异常信息相关调整。

Web 与任务进程要分别启动

应用服务器、后台任务、定时任务和交互命令往往加载不同的代码路径。迁移验证应分别启动它们，并执行数据库连接、队列收发、文件处理与错误报告等最小流程。若使用容器，还要确认基础镜像中的系统库满足原生 Gem 的需求。只跑单元测试不足以覆盖这些加载与配置差异。

发布时观察实际异常分布

采用可回退的分批方式部署，监测启动失败、请求异常、任务积压和内存增长。Ruby 支持状态、Bundler 行为和各 Gem 的版本约束可能调整，实施时请查看当期发布方与依赖维护信息。

可重复安装、可解释警告和分进程验证，是 Ruby 版本迁移比“更新解释器”更可靠的完成标准。