Rails 7/StimulusJS相对导入：开发环境正常，生产环境报错

问题背景 #

时隔数年重新使用Rails（上次用Rails 4），多个Stimulus控制器通过import '../metric_defaults.js'导入自定义Chart配置文件metric_defaults.js，内容如下：

Chart.defaults.elements.line.tension = 0.25;
Chart.defaults.elements.line.borderWidth = 5;

开发环境运行正常，但Heroku生产环境出现404错误：

Failed to load resource: the server responded with a status of 404 (Not Found) (metric_defaults.js)

已确认信息：

• 使用标准Rails 7配置（importmaps、sprockets）
• 生产服务器已预编译出带指纹的metric_defaults-9032be9e....js，但请求的是未加指纹的文件
• 文件路径：app/javascript/metric_defaults.js
• Stimulus控制器位于app/javascript/controllers/

解决思路 #

• 改用importmaps命名引用：在config/importmap.rb中添加映射规则：

  pin "metric_defaults", to: "metric_defaults.js"
  

  随后将Stimulus控制器中的导入语句改为：

  import "metric_defaults"
  

  Rails的importmaps会在生产环境自动处理指纹映射，避免相对路径导致的指纹不匹配问题。

• 检查sprockets资产配置：在config/initializers/assets.rb中确认配置：

  1. 确保app/javascript被加入资产路径：

     Rails.application.config.assets.paths << Rails.root.join("app/javascript")
     

  2. 确保目标文件被加入预编译列表：

     Rails.application.config.assets.precompile += %w( metric_defaults.js )
     

• 清理Heroku资产缓存：执行以下命令彻底重置生产环境资产：

  heroku run rails assets:clobber
  heroku run rails assets:precompile
  heroku restart
  

• 放弃相对路径导入：Rails 7的importmaps在生产环境对相对路径的指纹替换逻辑不稳定，改用命名引用是更可靠的方案。

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