文档教程知识库【免费下载链接】til:memo: Today I Learned项目地址https://gitcode.com/gh_mirrors/ti/til点击查看免费下载在 Heroku 上部署全新 Rails 应用时你可能会遇到本地开发环境与生产服务器 Ruby 版本不一致的问题本地跑得好好的代码上了生产却出现诡异的行为甚至报错。这篇指南基于作者的真实排障经历讲解如何用heroku run -- ruby --version快速核查 Heroku 运行实例上的实际 Ruby 版本并说明为什么仅仅在.ruby-version中声明版本还不够——必须同时在Gemfile中显式指定才能让 Heroku 在构建阶段锁定正确的 Ruby 版本。读完本文你将掌握一套「检查 → 修复 → 复验」的完整流程避免生产环境与本地开发环境的版本漂移。背景一次「版本以为是 4.0实际是 3.3」的排障作者在向 Heroku 部署一个全新 Rails 应用时遇到问题某个it块参数block argument特性始终不生效作者以为自己在用 Ruby 4.0理应支持该语法但行为却与之矛盾。这种「本地正常、生产异常」的典型症状往往指向一个容易被忽视的根源——生产服务器上的 Ruby 版本并不是你以为的那个版本。Heroku 的构建与运行体系是抽象化的你通常不直接管理服务器而是通过 Heroku CLI 间接与运行实例交互参见 ssh-into-heroku-server-hosting-app.md 中对heroku ps:exec的说明。正因如此生产环境实际使用的 Ruby 版本往往处于「黑盒」状态需要主动核查。用 heroku run 核查生产实例的实际 Ruby 版本Heroku 允许你在应用的一个一次性运行实例one-off dyno中执行任意命令。要确认该实例上的 Ruby 版本直接运行heroku run -- ruby --version作者实际执行的结果如下❯ heroku run -- ruby --version Running ruby --version on ⬢ my-app... up, run.3090 ruby 3.3.9 (2025-07-24 revision f5c772fc7c) [x86_64-linux]关键信息解读Running ruby --version on ⬢ my-app... up, run.3090表明命令被调度到一个名为run.3090的一次性 dyno 上执行应用名为my-appruby 3.3.9 (2025-07-24 revision f5c772fc7c)这是该实例上实际运行的 Ruby 版本——3.3.9属于 Ruby 3.3 系列[x86_64-linux]平台标识即 Linux x86_64 架构。作者由此发现自己实际处于3.3.9这应该是当时 Heroku 未显式指定版本时的默认回退版本fallback default。也就是说作者以为自己在 Ruby 4.0 上实际却在 3.3.9 上——这正是it块参数行为异常的根源。命令细节说明命令中--之后的部分ruby --version会原样传给一次性 dyno 的 shell 执行因此可以替换为任意命令例如ruby -v、which ruby或gem env如果需要在本地 Ruby 侧核对当前实际版本也可以使用RUBY_VERSION常量快速查看参见 list-the-running-ruby-version.md更多命令行选项可查看heroku run --help。为什么 .ruby-version 不够Gemfile 才是 Heroku 的版本契约作者其实已经在项目根目录的.ruby-version文件中设置了 Ruby 版本但疏忽了在Gemfile中同样声明版本。仅添加Gemfile中的版本声明并重新部署后生产实例上的 Ruby 版本才与预期一致❯ heroku run -- ruby --version Running ruby --version on ⬢ my-app... up, run.5353 ruby 4.0.0 (2025-12-25 revision 553f1675f3) PRISM [x86_64-linux]这次输出显示ruby 4.0.0并带有PRISM标记表明该构建基于 Prism 解析器与作者本地期望的版本一致。两种声明方式的作用域差异声明位置作用域对 Heroku 的影响.ruby-version本地开发工具链如 asdf、mise、RVM 等版本管理器读取用于在本机选择正确 RubyHeroku 的构建过程不依赖此文件来决定 Ruby 版本遗漏它不会报错但也不会生效Gemfileruby 4.0.0Bundler 在bundle install时校验并作为应用依赖的一部分随代码一起部署Heroku 在构建阶段据此安装对应版本的 Ruby这是生产版本锁定的关键值得注意的是.ruby-version文件在整个 Ruby 生态中主要服务本地版本管理器例如mise需要显式开启idiomatic_version_file_enable_tools [ruby]配置后才会读取该文件参见 look-in-ruby-version-dotfile.md。这进一步印证.ruby-version面向的是本地开发环境而不是 Heroku 的构建契约。而Gemfile是随应用一起打包并交给 Heroku Buildpack 的因此它才是生产环境 Ruby 版本的「权威来源」。推荐的完整配置为保证本地与生产版本一致最佳实践是两处同时声明.ruby-version供本地版本管理器使用4.0.0Gemfile供 Bundler 与 Heroku Buildpack 使用ruby 4.0.0关于 Ruby 版本文件生态仓库中还有 generate-ruby-version-and-gemset-files-with-rvm.md 与 install-latest-version-of-ruby-with-asdf.md 等笔记可供延伸参考。免去 --app 参数用环境变量指定默认应用与团队在上面的命令中作者之所以无需携带--app my-app参数是因为在其本地.envrc文件中预先导出了HEROKU_ORGANIZATION与HEROKU_APP两个环境变量参见 specify-default-team-and-app-for-project.md# Heroku export HEROKU_ORGANIZATIONvisualmode export HEROKU_APPmy-app设置并重新加载环境后herokuCLI 会自动以此为目标团队与应用heroku run、heroku config等命令都无需再显式传--app或--team大大简化日常排障操作。若你还没有这样配置则需要在命令中显式带上--appheroku run --app my-app -- ruby --version同理查看或管理应用的环境变量可参考 set-and-show-heroku-env-variables.md 中heroku config/heroku config:set/heroku config:get的用法。排障流程总结核查运行heroku run -- ruby --version或heroku run --app app-name -- ruby --version记录生产实例上的实际 Ruby 版本比对将该版本与本地ruby --version或 IRB 中的RUBY_VERSION输出比对确认是否一致修复若不一致确认Gemfile中已通过ruby x.y.z显式声明版本仅.ruby-version不足以影响 Heroku 构建必要时同步更新.ruby-version保持本地一致复验重新部署后再次运行第 1 步命令确认输出已切换到目标版本如本文示例中从3.3.9变为4.0.0。这套方法同样适用于排查依赖解析差异、语法兼容性如it块参数等一切与 Ruby 运行时版本相关的生产问题——先锁定版本再谈其他。赞分享文档教程知识库【免费下载链接】til:memo: Today I Learned项目地址https://gitcode.com/gh_mirrors/ti/til点击查看免费下载相关推荐使用 direnv 与 ruby-install 管理项目级 Ruby 版本从 .envrc 到 use ruby version 的完整实战指南使用 direnv 与 ruby install 管理项目级 Ruby 版本从 .envrc 到 use ruby version 的完整实战指南 dire开发工具CLIElastic Integrations监控数据可视化从图表到仪表盘的设计原则Elastic Integrations监控数据可视化从图表到仪表盘的设计原则 Elastic Integrations提供了强大的监控数据可视化能力帮助用可观测性数据集成后端DGCharts手势控制详解如何实现平滑的捏合缩放与平移拖拽DGCharts手势控制详解如何实现平滑的捏合缩放与平移拖拽 DGCharts 手势控制是这套开源图表库最出彩的部分——只需一行配置你的柱状图、折线图就支持数据可视化图表库移动开发上一篇emacs-libvterm安全考虑模块加载与权限管理的完整指南下一篇Windows苹果设备驱动一键安装快速解决iPhone连接问题的终极方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 Heroku 上检查并锁定生产应用的 Ruby 版本（.ruby-version 与 Gemfile 的双重保障）
文档教程知识库【免费下载链接】til:memo: Today I Learned项目地址https://gitcode.com/gh_mirrors/ti/til点击查看免费下载在 Heroku 上部署全新 Rails 应用时你可能会遇到本地开发环境与生产服务器 Ruby 版本不一致的问题本地跑得好好的代码上了生产却出现诡异的行为甚至报错。这篇指南基于作者的真实排障经历讲解如何用heroku run -- ruby --version快速核查 Heroku 运行实例上的实际 Ruby 版本并说明为什么仅仅在.ruby-version中声明版本还不够——必须同时在Gemfile中显式指定才能让 Heroku 在构建阶段锁定正确的 Ruby 版本。读完本文你将掌握一套「检查 → 修复 → 复验」的完整流程避免生产环境与本地开发环境的版本漂移。背景一次「版本以为是 4.0实际是 3.3」的排障作者在向 Heroku 部署一个全新 Rails 应用时遇到问题某个it块参数block argument特性始终不生效作者以为自己在用 Ruby 4.0理应支持该语法但行为却与之矛盾。这种「本地正常、生产异常」的典型症状往往指向一个容易被忽视的根源——生产服务器上的 Ruby 版本并不是你以为的那个版本。Heroku 的构建与运行体系是抽象化的你通常不直接管理服务器而是通过 Heroku CLI 间接与运行实例交互参见 ssh-into-heroku-server-hosting-app.md 中对heroku ps:exec的说明。正因如此生产环境实际使用的 Ruby 版本往往处于「黑盒」状态需要主动核查。用 heroku run 核查生产实例的实际 Ruby 版本Heroku 允许你在应用的一个一次性运行实例one-off dyno中执行任意命令。要确认该实例上的 Ruby 版本直接运行heroku run -- ruby --version作者实际执行的结果如下❯ heroku run -- ruby --version Running ruby --version on ⬢ my-app... up, run.3090 ruby 3.3.9 (2025-07-24 revision f5c772fc7c) [x86_64-linux]关键信息解读Running ruby --version on ⬢ my-app... up, run.3090表明命令被调度到一个名为run.3090的一次性 dyno 上执行应用名为my-appruby 3.3.9 (2025-07-24 revision f5c772fc7c)这是该实例上实际运行的 Ruby 版本——3.3.9属于 Ruby 3.3 系列[x86_64-linux]平台标识即 Linux x86_64 架构。作者由此发现自己实际处于3.3.9这应该是当时 Heroku 未显式指定版本时的默认回退版本fallback default。也就是说作者以为自己在 Ruby 4.0 上实际却在 3.3.9 上——这正是it块参数行为异常的根源。命令细节说明命令中--之后的部分ruby --version会原样传给一次性 dyno 的 shell 执行因此可以替换为任意命令例如ruby -v、which ruby或gem env如果需要在本地 Ruby 侧核对当前实际版本也可以使用RUBY_VERSION常量快速查看参见 list-the-running-ruby-version.md更多命令行选项可查看heroku run --help。为什么 .ruby-version 不够Gemfile 才是 Heroku 的版本契约作者其实已经在项目根目录的.ruby-version文件中设置了 Ruby 版本但疏忽了在Gemfile中同样声明版本。仅添加Gemfile中的版本声明并重新部署后生产实例上的 Ruby 版本才与预期一致❯ heroku run -- ruby --version Running ruby --version on ⬢ my-app... up, run.5353 ruby 4.0.0 (2025-12-25 revision 553f1675f3) PRISM [x86_64-linux]这次输出显示ruby 4.0.0并带有PRISM标记表明该构建基于 Prism 解析器与作者本地期望的版本一致。两种声明方式的作用域差异声明位置作用域对 Heroku 的影响.ruby-version本地开发工具链如 asdf、mise、RVM 等版本管理器读取用于在本机选择正确 RubyHeroku 的构建过程不依赖此文件来决定 Ruby 版本遗漏它不会报错但也不会生效Gemfileruby 4.0.0Bundler 在bundle install时校验并作为应用依赖的一部分随代码一起部署Heroku 在构建阶段据此安装对应版本的 Ruby这是生产版本锁定的关键值得注意的是.ruby-version文件在整个 Ruby 生态中主要服务本地版本管理器例如mise需要显式开启idiomatic_version_file_enable_tools [ruby]配置后才会读取该文件参见 look-in-ruby-version-dotfile.md。这进一步印证.ruby-version面向的是本地开发环境而不是 Heroku 的构建契约。而Gemfile是随应用一起打包并交给 Heroku Buildpack 的因此它才是生产环境 Ruby 版本的「权威来源」。推荐的完整配置为保证本地与生产版本一致最佳实践是两处同时声明.ruby-version供本地版本管理器使用4.0.0Gemfile供 Bundler 与 Heroku Buildpack 使用ruby 4.0.0关于 Ruby 版本文件生态仓库中还有 generate-ruby-version-and-gemset-files-with-rvm.md 与 install-latest-version-of-ruby-with-asdf.md 等笔记可供延伸参考。免去 --app 参数用环境变量指定默认应用与团队在上面的命令中作者之所以无需携带--app my-app参数是因为在其本地.envrc文件中预先导出了HEROKU_ORGANIZATION与HEROKU_APP两个环境变量参见 specify-default-team-and-app-for-project.md# Heroku export HEROKU_ORGANIZATIONvisualmode export HEROKU_APPmy-app设置并重新加载环境后herokuCLI 会自动以此为目标团队与应用heroku run、heroku config等命令都无需再显式传--app或--team大大简化日常排障操作。若你还没有这样配置则需要在命令中显式带上--appheroku run --app my-app -- ruby --version同理查看或管理应用的环境变量可参考 set-and-show-heroku-env-variables.md 中heroku config/heroku config:set/heroku config:get的用法。排障流程总结核查运行heroku run -- ruby --version或heroku run --app app-name -- ruby --version记录生产实例上的实际 Ruby 版本比对将该版本与本地ruby --version或 IRB 中的RUBY_VERSION输出比对确认是否一致修复若不一致确认Gemfile中已通过ruby x.y.z显式声明版本仅.ruby-version不足以影响 Heroku 构建必要时同步更新.ruby-version保持本地一致复验重新部署后再次运行第 1 步命令确认输出已切换到目标版本如本文示例中从3.3.9变为4.0.0。这套方法同样适用于排查依赖解析差异、语法兼容性如it块参数等一切与 Ruby 运行时版本相关的生产问题——先锁定版本再谈其他。赞分享文档教程知识库【免费下载链接】til:memo: Today I Learned项目地址https://gitcode.com/gh_mirrors/ti/til点击查看免费下载相关推荐使用 direnv 与 ruby-install 管理项目级 Ruby 版本从 .envrc 到 use ruby version 的完整实战指南使用 direnv 与 ruby install 管理项目级 Ruby 版本从 .envrc 到 use ruby version 的完整实战指南 dire开发工具CLIElastic Integrations监控数据可视化从图表到仪表盘的设计原则Elastic Integrations监控数据可视化从图表到仪表盘的设计原则 Elastic Integrations提供了强大的监控数据可视化能力帮助用可观测性数据集成后端DGCharts手势控制详解如何实现平滑的捏合缩放与平移拖拽DGCharts手势控制详解如何实现平滑的捏合缩放与平移拖拽 DGCharts 手势控制是这套开源图表库最出彩的部分——只需一行配置你的柱状图、折线图就支持数据可视化图表库移动开发上一篇emacs-libvterm安全考虑模块加载与权限管理的完整指南下一篇Windows苹果设备驱动一键安装快速解决iPhone连接问题的终极方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考