Rails7通过importmap引入无导出JS库（如jQuery）报错原因及正确方法

报错本质是两个机制共同导致的：

• 作用域隔离：importmap基于浏览器原生ES模块实现，所有模块内通过import导入的变量默认只在当前模块的私有作用域生效，不会自动挂载到全局window对象。而Fomantic UI（即报错里的semantic.js）是早期开发的UMD规范类库，没有适配ES模块的导入导出逻辑，初始化时只会从全局作用域查找jQuery/$变量，不会读取其他模块内部导入的jQuery。
• 静态导入提升：ES模块会在执行前静态解析所有import语句，将导入逻辑提升到模块最顶部优先执行。就算你在控制器代码里把jQuery的导入写在Fomantic UI导入之前，只要没有提前把jQuery挂载到全局，Fomantic UI执行时依然拿不到jQuery对象。
  你之前通过普通script标签引入jQuery能正常运行，是因为普通script没有模块作用域隔离，jQuery加载后会直接把自身挂载到window上，后续加载的Fomantic UI自然能从全局读到对应的变量。

所有依赖全局变量的非ES模块类库，不要在单个Stimulus控制器中引入，统一在项目的JS入口文件app/javascript/application.js中处理加载顺序和全局挂载，步骤如下：

1. 保留importmap.rb中的依赖映射配置，不需要额外修改：

# config/importmap.rb
pin "application", preload: true
pin "@hotwired/turbo-rails", to: "turbo.min.js", preload: true
pin "@hotwired/stimulus", to: "stimulus.min.js", preload: true
pin "@hotwired/stimulus-loading", to: "stimulus-loading.js", preload: true
pin_all_from "app/javascript/controllers", under: "controllers"
pin "jquery", to: "https://ga.jspm.io/npm:jquery@3.6.0/dist/jquery.js"
pin "fomantic-ui", to: "https://ga.jspm.io/npm:fomantic-ui@2.8.8/dist/semantic.js"
pin "nag", to: "https://cdnjs.cloudflare.com/ajax/libs/fomantic-ui/2.8.8/components/nag.min.js"

2. 在application.js中严格按照「引入依赖库→挂载全局变量→引入依赖全局变量的下游库」的顺序配置：

// app/javascript/application.js
import "@hotwired/turbo-rails"
import "controllers"

// 引入jQuery并挂载到全局，供所有依赖jQuery的老式类库调用
import jQuery from "jquery"
window.jQuery = jQuery
window.$ = jQuery

// 全局挂载完成后，再引入依赖jQuery的Fomantic UI及组件
import "fomantic-ui"
import "nag"

3. 简化Stimulus控制器代码，不需要在控制器中重复引入jQuery、Fomantic UI这类全局加载的依赖，直接使用全局挂载的$即可：

// app/javascript/controllers/hello_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    $('#fixednag').nag({
      persist: true
    })
  }
}

注意：Fomantic UI这类会全局注入组件方法的UI库，只需要在application.js入口加载一次即可，不要在多个控制器中重复引入，否则会出现重复初始化、加载顺序错乱的问题。

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