Rails 7项目引入Stimulus时Import Map模块解析错误排查

问题场景 #

在Rails 7应用中添加Hotwire功能时，配置Import Map引入Stimulus后，页面加载出现模块解析错误。

相关代码 #

importmap.rb #

pin "application"
pin "@hotwired/stimulus", to: "stimulus.min.js"

application.js #

import "stimulus.min.js"

application.html.erb #

<!DOCTYPE html>
<html>
  <head>
    <title>Chargemaster</title>
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>

    <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
    <%= javascript_importmap_tags %>
  </head>

  <body>
    hello
    <%= yield %>
  </body>
</html>

报错信息 #

TypeError: Failed to resolve module specifier "stimulus.min.js". Relative references must start with either "/", "./", or "../".

错误原因 #

Import Map的pin指令中，第一个参数是模块的别名（标识符），to后的字符串是该别名对应的实际文件路径。导入模块时必须使用定义的别名，而非文件路径。当前代码直接导入stimulus.min.js，浏览器会将其视为相对路径，但未按相对路径规则开头，导致解析失败。

解决方案 #

1. 修改application.js的导入语句，使用Import Map中定义的别名@hotwired/stimulus：

import "@hotwired/stimulus"

2. 完整的Stimulus初始化代码（建议补充）：

import { Application } from "@hotwired/stimulus"

window.Stimulus = Application.start()

// 若有自定义控制器，可在此注册
// import HelloController from "./controllers/hello_controller"
// Stimulus.register("hello", HelloController)

3. importmap.rb的配置无需修改，pin "@hotwired/stimulus", to: "stimulus.min.js"是正确的，它指向Rails通过Import Map管理的压缩版Stimulus文件。

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