升级Rails 6.1至7.0后turbo-rails与importmap-rails加载异常排查

1. 确认Gem是否被Rails实际加载 #

• 在Rails控制台执行 Gem.loaded_specs['turbo-rails'] 和 Gem.loaded_specs['importmap-rails']，返回nil则说明Gem未被加载：
  • 检查Gemfile里的gem声明是否误放在了特定环境组（比如仅development组，但你在其他环境运行）
  • 执行bundle install后必须重启服务器/控制台，Rails不会自动加载新添加的Gem

2. 手动挂载Gem的Rails引擎 #

turbo-rails和importmap-rails都是Rails引擎，拆分Rails核心组件时可能不会自动加载引擎：

• 打开config/application.rb，手动添加引擎加载代码：

  require "turbo/engine"
  require "importmap/engine"
  

• 重启控制台后，再次检查Turbo或Importmap类是否可用

3. 验证Zeitwerk自动加载配置 #

使用Zeitwerk时，需确保引擎代码能被正确扫描：

• 检查config/application.rb中的config.autoload_paths和config.eager_load_paths，确认未排除Gem的路径
• 执行 Rails.autoloaders.main.debug 查看Zeitwerk加载日志，确认是否加载了Gem的核心文件

4. 锁定Gem的兼容版本 #

部分新版本Gem仅支持Rails 7.1+，需匹配Rails 7.0的兼容版本：

• 在Gemfile中指定版本：

  gem "turbo-rails", "~> 1.0"
  gem "importmap-rails", "~> 1.1"
  

• 执行bundle update turbo-rails importmap-rails后重启应用

5. 补充必要的初始化配置 #

拆分Rails组件可能跳过了Gem的默认初始化：

• 对于turbo-rails，在config/initializers/assets.rb中添加资源预编译配置：

  Rails.application.config.assets.precompile += %w( turbo.js turbo.min.js turbo.es2017.js turbo.es2017.min.js )
  

• 查看Gem的本地源码（bundle open turbo-rails），确认是否有其他需要手动添加的初始化代码

6. 验证Bundle加载上下文 #

• 始终用bundle exec rails console/server启动应用，确保使用bundle指定的Gem版本
• 执行bundle show turbo-rails查看Gem安装路径，检查lib目录下核心文件（如turbo.rb、turbo/engine.rb）是否存在，缺失则执行bundle reinstall turbo-rails重新安装

7. 检查Rails默认配置加载 #

拆分Rails组件时需确保加载必要的默认配置：

• 在config/application.rb中添加 config.load_defaults 7.0，这会加载Rails 7.0的默认引擎加载逻辑
• 若未设置该配置，需手动引入require "rails/engine"，引擎依赖此组件才能正常工作

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