Ruby3.3.4+Rails7.1启动报错：未初始化常量Utils::ScriptsUtils::Utils

问题背景 #

正尝试将Ruby应用从Ruby 2.6.6升级到Ruby 3.3.4，同时将Rails从5.1跨版本升级到7.1，虽清楚跨大版本升级并非最佳实践，但受实际情况限制只能执行该操作。已成功生成Gemfile.lock，此前启动rails s时出现LoadError，通过将大量require替换为require_relative解决，但现在遇到Zeitwerk相关错误：

$ rails s
=> Booting Puma
=> Rails 7.1.3.4 application starting in development
=> Run `bin/rails server --help` for more startup options
Exiting
C:/Users/abris/.gem/ruby/3.3.0/gems/zeitwerk-2.6.16/lib/zeitwerk/cref.rb:91:in `const_get': uninitialized constant Utils::ScriptsUtils::Utils (NameError)
...（省略中间栈信息）
from bin/rails:4:in `<main>'

当前配置信息 #

• config/environment.rb第5行代码：Rails.application.initialize!
• application.rb中的加载配置：

config.eager_load = true
    config.eager_load_paths << "#{Rails.root}/lib/assets"
    config.eager_load_paths << "#{Rails.root}/lib/tasks"
    config.eager_load_paths << "#{Rails.root}/lib/utilities"
    config.eager_load_paths << Rails.root.join("lib")

    config.autoload_paths << Rails.root.join('lib')

解决思路 #

• 检查命名空间与文件结构匹配：Zeitwerk要求常量命名与文件路径严格对应。错误提示Utils::ScriptsUtils::Utils未初始化，需确认：
  • ScriptsUtils对应的文件是否为lib/utils/scripts_utils.rb（若属于Utils命名空间），或lib/scripts_utils.rb（若为顶层常量）；
  • 代码中是否错误在Utils::ScriptsUtils内部嵌套引用了Utils，导致Zeitwerk尝试加载不存在的Utils::ScriptsUtils::Utils。
• 清理eager_load_paths配置：当前同时添加了lib及多个子目录，Zeitwerk会自动处理父目录下的所有子目录，重复添加子目录可能引发加载冲突。建议仅保留config.eager_load_paths << Rails.root.join("lib")，移除lib/assets、lib/tasks、lib/utilities的单独配置；同时Rails 7+中autoload_paths已被Zeitwerk取代，直接删除config.autoload_paths << Rails.root.join('lib')，避免逻辑冲突。
• 修正常量引用方式：若ScriptsUtils代码中使用了Utils，未加前缀的Utils会被解析为当前命名空间下的Utils::ScriptsUtils::Utils，而非顶层Utils。需将代码中的Utils改为::Utils，明确引用顶层命名空间的常量。
• 启用Zeitwerk加载日志：启动时添加环境变量输出加载细节，执行命令：ZEITWERK_LOG=1 rails s，通过日志确认哪些文件被加载、哪些常量未被正确识别，定位加载顺序问题。
• 验证文件命名规范：确保所有Ruby文件采用snake_case命名，对应CamelCase的常量名（如ScriptsUtils对应scripts_utils.rb，Utils对应utils.rb），Zeitwerk依赖该映射关系自动加载常量。

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