Rails 7特定页面加载无依赖自定义JS的问题排查

一、先卸载误装的esbuild #

esbuild通过jsbundling-rails集成，按以下步骤卸载：

• 打开Gemfile，删除gem 'jsbundling-rails'，执行bundle install
• 打开package.json，删除scripts里的esbuild相关命令（比如"build": "esbuild app/javascript/application.js --bundle --sourcemap --outdir=app/assets/builds"），同时移除dependencies里的esbuild
• 删除app/assets/builds目录
• 检查config/initializers/assets.rb，如果有Rails.application.config.assets.paths << Rails.root.join("app/assets/builds")，删掉该行
• 打开app/views/layouts/application.html.erb，把esbuild生成的javascript_include_tag替换回Importmap的<%= javascript_importmap_tags %>
• 重启Rails服务器

二、修复自定义JS加载问题 #

1. 确认Importmap配置正确性 #

你已添加pin_all_from "app/javascript/plugin", under: "plugin"，可运行rails importmap:json查看生成的映射，确认plugin/xxx对应正确的文件路径（比如"plugin/auto-complete": "/assets/plugin/auto-complete-xxxx.js"）。

2. 正确加载自定义模块 #

不能直接用javascript_import_module_tag "plugin"，因为plugin是目录而非可导入模块，需指定具体模块：

• 在特定视图中按需加载：

  <%= javascript_import_module_tag "plugin/auto-complete" %>
  

• 全局按需加载（结合Turbo事件）：
  在app/javascript/application.js中添加：

  document.addEventListener('turbo:load', () => {
    // 仅当页面存在目标元素时加载模块
    if (document.querySelector('[data-auto-complete]')) {
      import('plugin/auto-complete').then((module) => {
        // 调用模块的初始化方法（假设你的JS暴露了init函数）
        module.init();
      });
    }
  });
  

三、处理浏览器兼容性问题 #

• Firefox：必须在about:config中开启dom.importMaps.enabled，开启后刷新页面重试
• Chrome：确保使用版本91及以上（默认支持Importmap），若仍报错，查看浏览器控制台的具体错误信息（比如404找不到文件、模块语法错误）

四、解决pin命令异常问题 #

如果替换pin_all_from为pin("plugin/auto-complete")仍报错，尝试显式指定文件路径：

# 在importmap.rb中
pin "plugin/auto-complete", to: "plugin/auto-complete.js"

重启服务器后，再次用rails importmap:json确认映射是否正确，同时检查app/javascript/plugin/auto-complete.js是否存在、文件名大小写是否匹配（Rails开发环境对大小写敏感）。

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