Rails6升级至Rails7后Stimulus控制器未加载问题排查

问题概述 #

将Rails 6应用升级至Rails 7，采用importmaps与Leaflet组件，参照相关教程操作后，新建应用可正常运行，但升级的旧应用中Stimulus控制器未加载——终端和Chrome控制台无报错，但Chrome开发者工具Sources面板中看不到加载的控制器文件。

一、核心配置遗漏点排查 #

1. 控制器目录与命名规范检查

   • 确保控制器文件放在app/javascript/controllers/下，文件名严格遵循[控制器名]_controller.js格式（如map_controller.js），类名对应为MapController并继承Stimulus.Controller。
   • 确认app/javascript/controllers/application.js存在，内容应为：

     import { Controller } from "@hotwired/stimulus"
     export default class extends Controller {}
     

2. Importmap映射验证

   • 执行rails importmap:install重新生成配置，确保pin_all_from "app/javascript/controllers", under: "controllers"未被注释。
   • 访问http://localhost:3000/rails/importmap.json，检查返回的JSON中是否包含所有控制器文件的映射（如"controllers/map_controller": "/app/javascript/controllers/map_controller.js"）。

3. 布局文件标签检查

   • 确保应用布局（如app/views/layouts/application.html.erb）中包含<%= javascript_importmap_tags %>，且未同时使用Webpacker遗留的javascript_pack_tag。

4. 加载顺序确认

   • 保证application.js中加载顺序正确：

     import "@hotwired/turbo-rails"
     import "controllers" // 必须在Turbo之后加载
     import "popper"
     import "bootstrap"
     

二、实用调试步骤 #

1. 强制刷新缓存

   • 使用Ctrl+Shift+R（Windows/Linux）或Cmd+Shift+R（Mac）强制刷新页面，避免浏览器缓存旧资源。

2. 验证Importmap资源加载

   • 在Chrome控制台执行importmap.resources，查看已加载资源列表，确认控制器文件是否存在。
   • 手动尝试加载控制器：执行import("controllers/[控制器名]_controller")，观察是否抛出错误。

3. 检查Stimulus实例状态

   • 在控制台执行Stimulus.application.controllers，查看已注册控制器列表。若为空，说明Stimulus未正确初始化。
   • 在controllers/index.js末尾添加console.log("Stimulus controllers loaded")，验证控制器加载逻辑是否执行。

4. 排查Sprockets与Importmap冲突

   • 检查config/application.rb中配置：

     config.assets.enabled = true
     config.importmap.enabled = true
     

   • 避免在Sprockets的application.js中重复加载Stimulus或Turbo资源。

5. 清理缓存并重启服务

   • 执行rails tmp:clear清理临时文件，重启Rails服务器确保配置生效。

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