ruby-upgrade 用于把 Ruby 应用从一个 Ruby 主/次版本升级到另一个版本,目前目标是从 Ruby 3.x 升级到 4.0.x。它是 Ruby 解释器层面的升级;Rails 框架版本升级(6.x → 7.x → 8.x、config.load_defaults、railsdiff)应使用 rubypowers:rails-upgrade 技能,两者常配合进行,建议先运行 Rails 升级的 Ruby 兼容性表确认目标 Ruby 受当前 Rails 支持。
主要能力:内置 references/ruby-4-0-changes.md 破坏性变更清单,作为检测模式与修复方式的唯一依据;覆盖 change-01 至 change-14 的全部条目,并额外列出包装 Net::HTTP 的 HTTP 客户端 gem。
两种模式:audit-only 在写完分析报告后停止(阶段 0–3);full(默认)在审计后应用机械性更新并验证。若未指定目标补丁版本,默认选目标线最新稳定版并说明所选版本。
使用流程分段:
- 阶段 0 验证仓库:用 git rev-parse --show-toplevel 与 test -f Gemfile && test -f Gemfile.lock 确认是 Bundler 项目,缺失则退出。
- 阶段 1 采集当前工具链:并行读取 .ruby-version、Gemfile(ruby 指令)、Gemfile.lock(RUBY VERSION、BUNDLED WITH 及 rails、sorbet/tapioca、openssl、logger、ostruct、benchmark、irb、reline、pry、debug、nokogiri、pg、grpc、ffi、bcrypt、msgpack 等版本)、Dockerfile、CI 配置(.github/workflows/.yml、.gitlab-ci.yml、.gitlab/ci/**/.yml、.circleci/config.yml)、.rubocop.yml 的 TargetRubyVersion、sorbet/config。
- 阶段 2 风险盘点:派发一个 Explore 子代理按变更清单扫描代码库,给出每项计数与最多 5 个 file:line 示例。
- 阶段 3 写分析报告到 docs/ruby-upgrade/<YYYY-MM-DD>/analysis.md,无 docs 目录则写 tmp/ruby-upgrade/<YYYY-MM-DD>/analysis.md,含 TL;DR(LOW/MEDIUM/HIGH 风险、工作量、前三大阻塞)、当前状态表、风险矩阵、分阶段清单、意外发现、待团队确认的问题。audit-only 模式到此停止并输出报告路径。
- 阶段 4 应用机械性工具链更新:建议分支名如 upgrade-ruby-4-0-5;仅修改阶段 1 中确实锁定旧版本的文件——.ruby-version 写目标版本;Dockerfile 将 FROM ...ruby:3.X.X 改为 ruby:<target>,保留私有镜像仓库前缀;CI YAML 中所有字面 Ruby 版本字符串;.rubocop.yml 设 TargetRubyVersion: <major.minor>;仅当应用代码直接使用被移除的 CGI API(change-02)时添加 gem "cgi",仅当直接需要且未被解析时添加 ostruct 等降级 gem(change-03)。随后执行 bundle update --ruby,失败则停止并将失败 gem 记入报告的 Blockers 章节。
- 阶段 5 验证:运行 bundle exec rubocop;项目用 RSpec 则 bundle exec rspec --fail-fast,否则 bundle exec rails test;存在 sorbet/config 时运行 bundle exec srb tc,使用 Tapioca 时运行 bundle exec tapioca gem 重新生成 RBI。失败时在报告中追加“Verification failures”并输出内容,或修复明显问题(RBI 过期、安全的 RuboCop 自动修正),否则停止并告知用户。若 bundle install 成功但测试在加载 C 扩展时崩溃,可能是 vendor/bundle 缓存针对旧 ABI 构建,可 rm -rf vendor/bundle && bundle install(change-09)。
- 阶段 6 合并后观察(建议,不自动执行):建议对错误追踪器做 24 小时监控,关注新的 ArgumentError/backtrace 指纹(change-10)、内部客户端 Net::HTTP 400/415 响应激增(change-01)、读取 Ruby 内部帧的日志抓取器出现新的解析错误。
硬性规则:不得只改 .ruby-version 而不同步修改所有 Dockerfile/CI 镜像(这是 Ruby 主版本升级最常见的部署故障);不得在应用代码未直接需要时自动添加 gem "ostruct" 等降级 gem(Rails 7.1+ 会传递锁定多个,重复添加会与 lock 冲突);不得在生产 4.0.x 上启用 --zjit(实验性),保留 YJIT;不得跳过阶段 2 的 grep 扫描,仅升级版本再跑测试会漏掉 CGI.parse、openssl 固定版本和监控指纹漂移。
适用场景:Bundler/Rails 应用的 Ruby 解释器主/次版本升级、升级到 Ruby 4、审计 Ruby 4 兼容性。限制:只面向 Bundler 项目;不负责 Rails 框架升级;不自动执行合并后监控。