Rails从6.0升级到6.1后自定义中间件LocaleMiddleware未被识别报错问题

核心原因说明 #

Rails 6.1 未在中间件变更文档中提及的核心调整是默认将Zeitwerk设为唯一自动加载器，替换了6.0版本中兼容的Classic自动加载器。Classic加载器对命名匹配、路径规则的宽松度更高，升级后常量加载规则收紧是触发uninitialized constant LocaleMiddleware错误的核心原因。

定位检查项 #

• 检查LocaleMiddleware的存放路径和命名是否符合Zeitwerk规则：自定义中间件默认应存放在app/middleware/目录下，文件名必须为蛇形命名的locale_middleware.rb，类名必须为完全对应的大驼峰LocaleMiddleware，大小写、命名拆分必须完全匹配，不能出现拼写偏差
• 检查config/application.rb中是否有将app/middleware加入自动加载路径的配置，Rails 6.1默认不会将该目录纳入Zeitwerk自动加载范围
• 检查中间件注册代码是否在Rails自动加载流程启动前执行，提前调用常量会触发未初始化错误

解决方案 #

方案1（最稳妥，无加载顺序冲突）：注册前显式加载中间件文件 #

直接在注册中间件前手动引入文件，跳过自动加载规则限制，适合只存在少量自定义中间件的场景：

# config/application.rb
require Rails.root.join('app', 'middleware', 'locale_middleware')

config.middleware.use LocaleMiddleware

方案2：将中间件目录纳入自动加载路径 #

如果存在大量自定义中间件，可统一将目录加入Zeitwerk加载范围：

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

# 后续正常注册中间件即可
config.middleware.use LocaleMiddleware

注意：不要同时使用显式require和加入自动加载路径两种方案，会触发Zeitwerk的重复常量定义警告。

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