Hanami 2.2项目启动时jquery.min.js的Node.js模块警告问题

这个警告的核心原因是你的项目通过package.json里的"type": "module"声明了所有.js文件默认作为ECMAScript(ES)模块处理，但你引入的jquery.min.js是CommonJS(CJS)格式的文件——它里面使用了CommonJS特有的module.exports语法。

在ES模块环境中，module变量不会像CommonJS里那样被自动注入，而是被当作一个全局变量处理，这可能导致jQuery的导出逻辑不符合预期，所以工具链抛出了这个警告。同时提示你：在"type": "module"的项目里，CommonJS文件应该使用.cjs后缀来明确标识。

方案1：修复.cjs后缀的jQuery引入问题 #

你之前重命名jquery.min.js为jquery.min.cjs后出现找不到jQuery的错误，是因为jQuery的UMD导出逻辑在ES模块环境下需要手动挂载到全局。修改app/assets/js/app.js的代码：

import "../css/app.css";
// 引入.cjs格式的jQuery并挂载到window
import $ from "./jquery.min.cjs";
window.$ = window.jQuery = $;
import "./test.js"

这样既符合"type": "module"的规范，又能让全局环境（比如test.js）正常访问jQuery。

方案2：通过npm安装官方jQuery包 #

手动引入本地jQuery文件容易引发模块格式冲突，更规范的做法是通过npm安装：

1. 执行安装命令：

npm install jquery

2. 修改app.js的引入代码：

import "../css/app.css";
import $ from "jquery";
window.$ = window.jQuery = $;
import "./test.js"

npm官方包的jQuery会自动适配ES模块环境，不会触发格式警告。

方案3：调整项目模块类型的全局设置 #

如果不想让整个项目默认使用ES模块，可以移除package.json里的"type": "module"字段，然后在需要作为ES模块的目录（比如app/assets/js）下新建一个package.json，仅在这个文件里设置：

{
  "type": "module"
}

这样项目默认是CommonJS环境，jquery.min.js就能被正确识别，不会触发警告。不过这种方式需要调整项目的模块结构，适合对模块格式有特殊需求的场景。

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