Ruby on Rails 7.x.x无法渲染public文件夹及自定义404页面的问题

常见问题原因 #

1. Render 文件路径解析错误：Rails 7 对相对路径的解析逻辑有调整，直接使用 'public/404.html' 作为相对路径时，框架可能无法正确定位到文件位置。
2. Public 文件服务未启用：生产环境下 Rails 默认可能关闭了 public_file_server，导致无法直接访问 public 文件夹下的静态资源。
3. 自定义错误处理与默认机制冲突：全局 rescue_from 的写法可能和 Rails 7 内置的错误页面处理逻辑（config.exceptions_app）产生冲突。
4. 浏览器缓存干扰：favicon 这类静态资源容易被浏览器缓存，即使文件存在也可能显示旧内容或无法加载。

针对性解决方案 #

1. 修正 404 页面的 Render 路径 #

修改你自定义的 ErrorHandling Concern 中的 notfound 方法，使用基于 Rails.root 的绝对路径：

module ErrorHandling
  extend ActiveSupport::Concern

  included do
    rescue_from ActiveRecord::RecordNotFound, with: :notfound

    private

    def notfound(exception)
      logger.warn exception
      # 使用绝对路径定位 public 下的 404.html
      render file: Rails.root.join('public', '404.html'), status: :not_found, layout: false
    end
  end
end

2. 启用 Public 文件服务 #

打开对应环境的配置文件（比如 config/environments/production.rb），确保开启静态文件服务：

# 启用 public 文件夹的静态文件服务
config.public_file_server.enabled = true

# 可选：设置缓存控制头，优化静态资源加载
config.public_file_server.headers = {
  'Cache-Control' => "public, max-age=#{1.year.to_i}"
}

3. 改用 Rails 推荐的错误页面处理方式 #

如果全局 rescue_from 仍有问题，可以切换到 Rails 7 推荐的 config.exceptions_app 机制：

• 在 config/application.rb 或对应环境配置中添加：

  config.exceptions_app = self.routes
  

• 在 config/routes.rb 中添加错误路由：

  # 捕获所有非 AJAX 的 HTML 请求错误
  get '*path', to: 'errors#not_found', constraints: ->(req) { !req.xhr? && req.format.html? }
  

• 创建 app/controllers/errors_controller.rb：

  class ErrorsController < ApplicationController
    def not_found
      render status: :not_found
    end
  end
  

• 将 public/404.html 移动到 app/views/errors/not_found.html.erb（保持内容不变），这样框架会自动按视图路径查找文件，避免路径问题。

4. 解决 Favicon 加载问题 #

• 确保 favicon.ico 放在 public 文件夹根目录，直接访问 http://your-domain/favicon.ico 验证是否能加载。
• 清除浏览器缓存（快捷键 Ctrl+Shift+R 强制刷新），避免缓存导致的加载异常。
• 若使用 Asset Pipeline，可将 favicon.ico 放入 app/assets/images/，然后在布局文件中添加：

  <%= favicon_link_tag 'favicon.ico' %>
  

  Rails 会自动处理资源路径，确保正确加载。

验证步骤 #

1. 重启 Rails 服务器，确保所有配置修改生效。
2. 访问一个不存在的路由，检查 404 页面是否正常显示。
3. 直接访问 /404.html 和 /favicon.ico，确认静态资源能正常加载。

内容的提问来源于stack exchange，提问作者Иван Сизых