新部署至Fly.io的Rails7.0.8应用无法加载图片及JS资源求助

可能的问题点及解决步骤 #

1. Stimulus控制器的ImportMaps配置错误 #

• 确认config/importmap.rb中正确pin了所有Stimulus控制器：

  pin "@hotwired/stimulus", to: "stimulus.min.js", preload: true
  pin "@hotwired/stimulus-loading", to: "stimulus-loading.js", preload: true
  pin_all_from "app/javascript/controllers", under: "controllers"
  

• 检查app/javascript/controllers/index.js是否正确注册控制器：

  import { Application } from "@hotwired/stimulus"
  const application = Application.start()
  
  // 加载所有控制器文件
  import controllers from "./**/*_controller.js"
  controllers.forEach((controller) => {
    application.register(controller.name, controller.module.default)
  })
  

• 生产环境下必须执行ImportMaps编译命令，确保控制器被正确打包：

  RAILS_ENV=production rails importmap:compile
  

  执行后再运行资产预编译，或者在Fly的部署钩子中添加该命令（修改fly.toml）：

  [deploy]
    release_command = "bundle exec rails importmap:compile && bundle exec rails assets:precompile"
  

2. 图片资源引用路径未使用Rails Asset Helper #

• 视图中引用图片必须用image_tag helper，而非硬编码路径：

  <%= image_tag "mountains.jpg" %>
  

• CSS中引用图片需用asset_path或image_path helper（如果用SCSS）：

  .bg-mountains {
    background-image: url(<%= asset_path("mountains.jpg") %>);
  }
  

• 若使用Tailwind CSS自定义背景图，需在tailwind.config.js中配置正确的资源路径，并确保Rails能解析：

  module.exports = {
    content: [
      "./app/views/**/*.html.erb",
      "./app/javascript/**/*.js"
    ],
    theme: {
      extend: {
        backgroundImage: {
          'mountains': "url('<%= asset_path('mountains.jpg') %>')"
        }
      }
    }
  }
  

3. 生产环境资产配置补充 #

• 确认config/environments/production.rb中的资产相关配置：

  # 禁用动态编译（生产环境必须关闭）
  config.assets.compile = false
  # 确保静态文件服务启用（已通过环境变量设置，这里再次确认）
  config.public_file_server.enabled = ENV["RAILS_SERVE_STATIC_FILES"].present?
  # 可选：设置正确的缓存头，避免浏览器缓存旧资源
  config.public_file_server.headers = {
    "Cache-Control" => "public, max-age=31536000"
  }
  

• 检查是否误设置了config.asset_host，若没有使用CDN，应注释或删除该配置。

4. 预编译资产的完整性验证 #

• 本地预编译后，检查public/assets目录：
  • 图片是否生成带指纹的版本（如mountains-abc123def456.jpg）
  • public/assets/.sprockets-manifest-*.json中是否有该图片的映射记录
• 通过flyctl ssh console进入Fly服务器，执行以下命令验证文件存在：

  # 检查图片文件
  ls public/assets | grep mountains
  # 检查ImportMaps编译后的控制器相关文件
  ls public/assets/importmaps/
  

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