升级Ruby 3.1.3与Rails 6.1时遭遇NameError: uninitialized constant错误求助

算力阿峰

2026-7-19

解决Rails 6.1 + Ruby 3.1.3下的NameError: uninitialized constant Area问题

问题根源

Zeitwerk自动加载机制冲突：Rails 6.1默认使用Zeitwerk作为自动加载器，它遵循"目录对应模块、文件对应类/模块"的规则。你的app/models/area/目录会被Zeitwerk识别为模块Area的容器，但你已经在area.rb中将Area定义为类，导致常量冲突。
多余的自动加载路径配置：手动添加config.autoload_paths += Dir["#{config.root}/app/models/**/"]会干扰Zeitwerk的默认加载逻辑，因为Zeitwerk本身会递归加载app/models下的所有文件。
模块定义时依赖未加载的常量：加载search.rb时，Area类还未被加载，直接定义module Area::Search会触发未初始化常量的错误。

解决方案

步骤1：移除多余的自动加载配置

打开config/application.rb，删除以下代码：

config.autoload_paths += Dir["#{config.root}/app/models/**/"]

步骤2：调整目录结构（推荐方案）

将嵌套模块迁移到Rails推荐的concerns目录，避免类名与目录名冲突：

创建app/models/concerns/area/目录
将app/models/area/search.rb和app/models/area/constants.rb移动到这个新目录下

修改search.rb的模块定义（修正潜在语法错误）：

module Area::Search
  extend ActiveSupport::Concern

  included do
    # 这里写你的初始化逻辑或方法
  end

  # 定义模块实例方法
  def some_search_method
    # ...
  end
end

备选方案：在类中直接定义嵌套模块

如果不想调整目录，可以直接在area.rb中定义Area::Search模块，删除app/models/area/目录及其中文件：

class Area < ApplicationRecord
  module Search
    extend ActiveSupport::Concern

    included do
      # 初始化逻辑
    end

    def some_search_method
      # ...
    end
  end

  include Search

  # 你的类方法和实例方法
end