Rails7+Importmaps引入jQuery后jquery-ui提示jQuery未定义

问题描述 #

将旧项目升级到使用 Importmaps 的 Rails 7 时，遇到依赖配置问题。现有代码依赖 jQuery 和 jquery-ui，已配置导入两者，但 jquery-ui 模块中提示无法识别 jQuery 变量。

当前配置 #

config/importmap.rb：

pin "application", preload: true
pin "jquery", to: "https://ga.jspm.io/npm:jquery@3.6.3/dist/jquery.js", preload: true
pin "jquery-ui", to: "https://ga.jspm.io/npm:jquery-ui@1.13.2/ui/widget.js", preload: true

app/javascript/application.js：

import "jquery";
import "jquery-ui";

报错信息 #

Uncaught ReferenceError: jQuery is not defined
at widget.js? [sm]:20:11

解决方案 #

问题出在 jquery-ui 的依赖逻辑——它期望全局作用域存在 jQuery/$ 变量，但 ES 模块导入的 jQuery 不会自动挂载到全局。需要手动暴露全局变量，同时调整导入配置：

1. 修改 application.js，先挂载全局 jQuery：

import $ from "jquery";
// 将 jQuery 和 $ 挂载到全局，满足 jquery-ui 的依赖需求
window.jQuery = window.$ = $;
// 再导入 jquery-ui
import "jquery-ui";

2. 调整 importmap 中 jquery-ui 的 pin 地址：
   原配置仅指向单个 widget.js，建议替换为完整的 jquery-ui 入口（按需导入组件也可，但需保证全局已挂载 jQuery）：

pin "application", preload: true
pin "jquery", to: "https://ga.jspm.io/npm:jquery@3.6.3/dist/jquery.js", preload: true
# 替换为完整的 jquery-ui 入口文件
pin "jquery-ui", to: "https://ga.jspm.io/npm:jquery-ui@1.13.2/jquery-ui.js", preload: true

如果仅需特定组件（如 datepicker、sortable），可单独 pin 对应文件：

pin "jquery-ui/widget", to: "https://ga.jspm.io/npm:jquery-ui@1.13.2/ui/widget.js"
pin "jquery-ui/datepicker", to: "https://ga.jspm.io/npm:jquery-ui@1.13.2/ui/datepicker.js"

对应的 application.js 保持全局挂载逻辑，再导入指定组件：

import $ from "jquery";
window.jQuery = window.$ = $;
import "jquery-ui/widget";
import "jquery-ui/datepicker";

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