Rails：无规范命名空间下如何让常量首次自动加载成功？

Let's tackle this autoload issue step by step—you're right that the default Rails convention isn't matching your desired component structure, and that first-load failure is definitely frustrating. Here's how to get Components::Foo and Components::Bar loading correctly on the first try, without manual requires or constant nesting.

Core Problem #

Rails' default autoloader (Zeitwerk, used in Rails 6+) follows a strict "directory = module, file = class" convention. So when you have app/components/foo/foo.rb, it expects that file to define Components::Foo::Foo, not Components::Foo. Your current eager_load_paths config is adding all subdirectories to the load path, which creates confusion instead of fixing the mapping.

Solution for Rails 6+ (Zeitwerk) #

We need to tell Zeitwerk explicitly that each component file maps directly to the Components module, not a nested submodule. Here's how to set this up:

1. Update Load Paths #

First, clean up your load path config in config/application.rb—we only need to add the root app/components directory, not all its subdirectories:

# config/application.rb
config.autoload_paths << Rails.root.join('app/components')
config.eager_load_paths << Rails.root.join('app/components')

2. Customize Zeitwerk's Constant Mapping #

Next, add a dynamic rule to map each component's file to the correct top-level component class. This avoids having to manually list every component:

# config/application.rb
components_root = Rails.root.join('app/components')

# Iterate over each component directory
Dir.glob(components_root.join('*')).select { |path| File.directory?(path) }.each do |component_dir|
  component_slug = File.basename(component_dir)
  target_class = "Components::#{component_slug.camelize}"
  component_file = component_dir.join("#{component_slug}.rb")

  # Tell Zeitwerk this file defines the target constant
  Rails.autoloaders.main.customize(component_file => target_class) if File.exist?(component_file)
end

3. Verify Your Component Class Definitions #

Make sure your .rb files define the class directly under the Components module, not a nested submodule. For app/components/foo/foo.rb:

# app/components/foo/foo.rb
module Components
  class Foo
    # Your component logic here
  end
end

4. Restart Your Server #

Zeitwerk reads these configs on startup, so you'll need to restart your Rails server for the changes to take effect.

Why This Fixes the First-Load Failure #

By customizing the constant mapping, you're telling Zeitwerk exactly where to find Components::Foo on the first lookup—no more waiting for partial autoloads to kick in on the second request. This also ensures production environments will load the constants correctly on the first try, avoiding runtime errors.

For Rails 5 or Earlier (Classic Autoloader) #

If you're stuck on an older Rails version using the classic autoloader, you can adjust the autoload paths to prioritize your component files:

# config/application.rb
config.autoload_paths += Dir[Rails.root.join('app/components', '*')]
config.eager_load_paths += Dir[Rails.root.join('app/components', '*')]

Just ensure your class definitions follow the same module Components; class Foo; ...; end structure, and you should see the first-load issue resolved.

Key Notes to Avoid Future Issues #

• Don't add **/ to your load paths—this creates duplicate lookup paths and confuses the autoloader.
• Never use manual require statements for these components, as they bypass Rails' autoloading system and require server restarts when you make changes.

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