Rails 6中lib目录Ruby模块预加载失败及Zeitwerk命名错误问题

问题原因 #

Rails 6及以上版本默认使用Zeitwerk作为自动加载器，它严格遵循文件路径与常量命名空间一一对应的规则，你遇到的报错本质是规则不匹配导致的：

• 你将lib目录加入了自动/预加载路径，Zeitwerk会将lib视为顶层命名空间的根目录
• 你的文件路径为lib/production_key_generator.rb，按照规则Zeitwerk默认期望该文件定义顶层常量ProductionKeyGenerator
• 但你实际在文件中定义的是嵌套两层的常量Rails::Generators::ProductionKeyGenerator，和路径规则不匹配，因此Zeitwerk校验时抛出「未定义对应类」的错误。

其他现象说明 #

1. 首次调用报uninitialized constant Rails::Generators的原因：开发环境默认未开启eager_load，启动时不会主动预加载lib下的文件，你第一次访问常量时Zeitwerk找不到符合规则的加载路径，因此抛出未初始化常量的错误。
2. 手动require后可以正常访问的原因：require语句本身会直接执行目标文件的全部代码，Zeitwerk的校验报错是在文件执行完成后触发的，此时Rails::Generators::ProductionKeyGenerator类已经被加载到Ruby内存中，因此后续调用可以正常访问。

解决方案 #

方案1：遵循Zeitwerk命名约定（推荐） #

按照常量的命名空间创建对应嵌套目录，将production_key_generator.rb移动到如下路径：

lib/rails/generators/production_key_generator.rb

路径和命名空间完全匹配后，Zeitwerk可以正常自动加载该类，无需手动require。

方案2：跳过Zeitwerk管理lib目录 #

如果不想调整目录结构，可以在config/application.rb中配置让Zeitwerk忽略lib目录，改为手动管理加载：

config.eager_load_paths << Rails.root.join("lib")
# 新增这行，让Zeitwerk跳过lib目录的自动加载校验
Rails.autoloaders.main.ignore(Rails.root.join("lib"))

之后你可以在初始化脚本中批量require lib下的文件，或者在使用前手动require对应文件即可。

注意事项 #

如果需要在开发环境测试预加载效果，需要修改config/environments/development.rb，开启预加载配置：

config.eager_load = true

开发环境默认该配置为false，启动时不会主动加载预加载路径下的所有文件。

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