开发环境正常生产环境类未加载？Ruby版本与NameError问题排查

我遇到了开发环境和预发布（生产）环境的行为差异：本地能正常执行的操作，在预发布环境触发了以下错误：

#<NameError: uninitialized constant #<Class:0x0000557d7c986aa8>::Report>
/app/app/models/cart.rb:26:in `add_product'
/app/app/controllers/cart_controller.rb:10:in `add_remove'
/app/vendor/bundle/ruby/2.3.0/gems/actionpack-5.2.0/lib/action_controller/metal/basic_implicit_render.rb:6:in `send_action'

我怀疑是预发布环境的Ruby版本和本地不一致，我的Gemfile里明确指定了：

ruby '2.3.6'

但更新后发现本地日志同样显示Ruby 2.3.0：

/Users/myuser/.gem/ruby/2.3.0/gems/actionpack-5.2.0/lib/action_controller/metal/basic_implicit_render.rb:6:in `send_action'

我显然有认知误区，请问我遗漏了什么？Gems是否总是运行在Ruby最低补丁版本？

一、先澄清Ruby版本的认知误区 #

你在Gemfile里写的ruby '2.3.6'并不是自动帮你切换或安装Ruby版本的指令——它只是给Bundler的一个版本约束：告诉Bundler你的应用需要Ruby 2.3.6才能正常运行，如果当前环境的Ruby版本不匹配，Bundler应该抛出错误。

那为什么日志里显示的是2.3.0？原因很简单：

• 你本地和预发布环境实际运行的Ruby版本就是2.3.0，Gemfile的约束没生效。这可能是因为你没使用版本管理工具（比如rbenv、rvm）来指定项目的Ruby版本，系统直接用了默认的Ruby 2.3.0；或者你在执行bundle install时加了--ignore-ruby参数，跳过了版本检查。
• 日志里的2.3.0是当前环境的Ruby主版本号，gems会安装到对应版本的目录下，所以不管你Gemfile写了什么，只要环境是2.3.0，gems就会放在ruby/2.3.0目录里——这和“gems运行在最低补丁版本”完全没关系，补丁版本（比如2.3.6）是Ruby本身的版本，gems是基于当前Ruby版本运行的。

解决版本问题的步骤：

• 本地：用rbenv或rvm安装Ruby 2.3.6，然后在项目目录下执行rbenv local 2.3.6（rvm用户用rvm use 2.3.6 --default），确保终端会话切换到2.3.6后，重新执行bundle install。
• 预发布环境：确认服务器已安装Ruby 2.3.6，并且部署脚本（比如Capistrano）里配置了切换到该版本，重新部署应用。

二、再解决NameError的核心问题 #

这个错误和Ruby版本关系不大，更可能是Rails加载机制的环境差异：

• 本地开发模式下，Rails会开启自动加载（config.cache_classes = false），当代码用到Report类时，Rails会自动去app/models目录下找对应的文件加载。
• 预发布（生产）模式下，Rails默认关闭自动加载，开启预加载（config.eager_load = true），所有类需要在应用启动时就被加载完成。如果Report模型的文件名不符合Rails约定（比如应该是report.rb，你写成了reports.rb或其他名字），或者文件放在了非标准路径下，预加载时就找不到这个类，导致报错。
• 另外也有可能是预发布环境的代码部署不完整，app/models/report.rb文件没被正确上传到服务器。

排查NameError的步骤：

1. 登录预发布服务器，检查app/models目录下是否存在report.rb文件，文件名必须是小写单数，和类名Report对应（Rails的命名约定是类名驼峰，文件名蛇形小写单数）。
2. 打开report.rb文件，确认类定义是class Report < ApplicationRecord（或对应的父类），没有拼写错误。
3. 在预发布环境的Rails控制台里执行require 'report'，如果报错，说明文件路径或命名有问题；如果成功，那可能是预加载配置的问题，检查config/environments/production.rb里的config.eager_load是否为true。
4. 重新部署预发布环境，确保所有代码文件都被正确上传。

内容的提问来源于stack exchange，提问作者pixelearth