Rails 7生产环境Import Maps未使用预编译JS资源问题求助

问题现象 #

• 开发环境执行./bin/importmap json可正常返回带/assets前缀、带哈希指纹的JS资源映射，所有JavaScript功能运行正常，返回结果示例：

{
  "imports": {
    "application": "/assets/application-a7fd3fc58be844f89656edec1ec73e18f9ab627e54b2aea67a97aad4613b6305.js",
    "@hotwired/turbo-rails": "/assets/turbo.min-96cbf52c71021ba210235aaeec4720012d2c1df7d2dab3770cfa49eea3bb09da.js",
    "@hotwired/stimulus": "/assets/stimulus.min-900648768bd96f3faeba359cf33c1bd01ca424ca4d2d05f36a5d8345112ae93c.js",
    "@hotwired/stimulus-loading": "/assets/stimulus-loading-1fc59770fb1654500044afd3f5f6d7d00800e5be36746d55b94a2963a7a228aa.js",
    "stimulus": "https://ga.jspm.io/npm:stimulus@2.0.0/dist/stimulus.umd.js",
    "stimulus-use": "https://ga.jspm.io/npm:stimulus-use@0.41.0/dist/index.js",
    "hotkeys-js": "https://ga.jspm.io/npm:hotkeys-js@3.8.8/dist/hotkeys.esm.js",
    "trix": "/assets/trix-1563ff9c10f74e143b3ded40a8458497eaf2f87a648a5cbbfebdb7dec3447a5e.js",
    "@rails/actiontext": "/assets/actiontext-28c61f5197c204db043317a8f8826a87ab31495b741f854d307ca36122deefce.js"
  }
}

• 生产环境执行相同命令时，本地JS资源映射均不带/assets前缀与指纹后缀，例如application映射为/application.js，访问对应路径返回404，所有JavaScript功能完全失效。
• 已确认部署时资源已正常编译为带指纹的文件存放在public/assets目录，但应用尝试引用app/javascript目录下的原始脚本路径，这类路径无法被应用正常服务。
• 复现场景：Render.com、Heroku部署均出现相同问题。
• 现有配置信息：
  部署构建脚本：

  #!/usr/bin/env bash
  # exit on error
  set -o errexit
  
  bundle install
  bundle exec rake assets:precompile
  bundle exec rake assets:clean
  bundle exec rake db:migrate
  

  production.rb静态文件服务配置：config.public_file_server.enabled = ENV['RAILS_SERVE_STATIC_FILES'].present? || ENV['RENDER'].present?，生产环境下该配置求值为true。

问题根因 #

该问题由两类常见配置错误触发：

1. 构建阶段未显式指定RAILS_ENV=production：Render、Heroku等PaaS平台的构建流程默认不会自动注入生产环境标识，导致assets:precompile任务实际按开发环境规则执行，Import Maps不会生成带哈希指纹、带/assets前缀的资源路径，直接回退到引用app/javascript下的源文件路径。
2. 构建脚本中assets:clean任务执行逻辑异常：默认的assets:clean任务会删除未被Sprockets清单引用的资产，如果预编译阶段Import Maps的资源映射未及时写入主清单，刚生成的带指纹JS文件会被判定为无效资源清理，最终Import Maps只能返回无指纹的原始路径。

修复方案 #

按以下步骤调整即可解决：

1. 调整构建脚本，显式指定所有资产相关命令的运行环境为生产环境，同时给assets:clean传入保留版本参数，避免误删当前生效资产：

#!/usr/bin/env bash
set -o errexit

bundle install
# 显式指定生产环境执行预编译
RAILS_ENV=production bundle exec rake assets:precompile
# 仅清理超过10个历史版本的旧资产，不删除当前版本关联资源
RAILS_ENV=production bundle exec rake assets:clean[10]
RAILS_ENV=production bundle exec rake db:migrate

2. 在config/environments/production.rb中显式配置Import Maps生产环境规则，避免环境变量异常导致配置失效：

# 强制生产环境Import Maps使用带哈希指纹的资产路径
config.importmap.digest = true
# 确认资产前缀为默认的/assets
config.assets.prefix = "/assets"

3. 在部署平台的环境变量配置页，显式添加RAILS_ENV=production，确保构建、运行阶段都加载生产环境配置。
4. 重新部署后，在生产环境应用控制台执行./bin/importmap json验证，确认返回的本地JS路径都带/assets前缀和哈希指纹即修复完成。

注意：不要在本地开发环境直接执行生产环境的importmap命令，本地没有生产环境编译生成的资产清单，返回结果不具备参考性。

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