1. Rails 对 Ruby 的版本要求
- Rails 8.0 要求最低 Ruby 3.2.0 版本。
2. Ruby 版本声明的历史变化
Rails 项目中声明 Ruby 版本的方式经历了阶段性变化，关键节点总结如下：
| 时间/版本 | Rails 行为 | 说明 |
|---|---|---|
| Rails ≤5.2 | 在 Gemfile 中添加 ruby "x.x.x" | Specifying a Ruby Version - Bundler |
| Rails 5.2 | 引入 .ruby-version 文件，辅助版本管理 | 参考 PR #30016 |
| Rails 7.1.5 | Gemfile.tt 模板仍保留 ruby 版本声明 | - |
| Rails ≥7.2 | 取消 Gemfile 中的 ruby 声明 | 推荐由 .ruby-version 统一管理 Ruby 版本 |
3. .ruby-version 文件的作用与生成机制
- 新建 Rails 项目时，默认会在项目根目录生成 .ruby-version，用于记录当前 Ruby 版本。
- 生成逻辑基于模板 ruby-version.tt：
<%= ENV["RBENV_VERSION"] || ENV["rvm_ruby_string"] || "#{RUBY_ENGINE}-#{RUBY_ENGINE_VERSION}" %>
具体规则：
- 如果环境变量 RBENV_VERSION 或 rvm_ruby_string 存在，则 .ruby-version 写入纯版本号（如 3.3.1）。
- 否则，写入带前缀的格式（如 ruby-3.3.1），这在某些版本管理工具（如 rbenv ）中可能导致兼容性问题。
4. Capistrano + rbenv 部署中的问题
使用 capistrano/rbenv 部署时，常见读取 Ruby 版本的方式是：
set :rbenv_ruby, File.read('.ruby-version').strip
如果 .ruby-version 是 ruby-x.y.z 格式，rbenv 可能解析失败，导致部署报错。
5. ✅ 推荐最佳实践，避免部署失败
1. 在本地开发环境优先通过 RBENV_VERSION 变量设置版本
例如，执行：
rbenv shell 3.3.8
或直接导出环境变量：
export RBENV_VERSION=3.3.8
2. 如果已有项目，手动修正 .ruby-version 文件
确保其内容为纯版本号，例如：
3.3.8
