Rails 7.1.2应用未预编译时CSS修改不生效问题求助

问题概述 #

全新默认搭建的Rails 7.1.2应用，未执行rails assets:precompile时修改SCSS文件无法实时生效；执行预编译后一切正常，说明资源路径配置无问题，但开发环境的实时编译机制异常。

环境信息 #

• Rails版本：7.1.2
• Ruby版本：ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [x86_64-linux]
• 操作系统：Ubuntu
• config/environments/development.rb相关配置：

config.public_file_server.enabled = true
config.action_controller.perform_caching = false
config.cache_store = :null_store
config.assets.debug = true
config.assets.compile = true
config.cache_classes = false

已完成的排查操作 #

• 确认config.assets.debug和config.assets.compile已设为true
• 开发环境已禁用缓存
• 清除浏览器缓存、使用无痕模式测试
• 多次重启Rails服务器
• 检查SCSS文件无语法错误
• 确认listen gem已安装并正常运行

可能原因及解决建议 #

1. 资产未在manifest.js中声明 #

Rails 7.1起，开发环境默认通过sprockets的app/assets/config/manifest.js管理资产编译范围。如果SCSS文件未被正确导入，开发环境不会自动编译未声明的资产。

• 解决：打开app/assets/config/manifest.js，确保包含目标SCSS文件，示例配置：

//= link_tree ../images
//= link_tree ../stylesheets .css
//= link application.js

link_tree ../stylesheets .css会包含stylesheets目录下所有CSS/SCSS文件，若有单独文件需要显式声明，可添加//= link custom.scss。

2. 预编译资产残留干扰 #

执行assets:precompile后生成的public/assets目录，会让开发环境优先读取预编译文件，而非实时编译源码。

• 解决：删除预编译资产目录并重启服务器：

rm -rf public/assets
rails s

3. Sprockets缓存未清除 #

即便禁用了全局缓存，Sprockets的本地缓存可能残留旧编译文件，导致修改不触发重新编译。

• 解决：清除临时缓存文件：

rails tmp:clear

该命令会删除tmp/cache/assets下的缓存，强制Sprockets重新编译。

4. 资产监听目录配置缺失 #

Rails 7.1对文件监听的默认配置可能未覆盖资产目录，导致文件修改未被检测到。

• 解决：在config/environments/development.rb中添加监听配置：

config.file_watcher = ActiveSupport::EventedFileUpdateChecker
config.watchable_dirs['app/assets'] = [:scss, :css, :js, :png, :jpg, :gif]

重启服务器后，确保修改SCSS时控制台能输出文件变更日志。

5. 浏览器缓存策略冲突 #

部分浏览器可能忽略缓存禁用设置，强制缓存静态资源。

• 解决：在config/environments/development.rb中设置严格的缓存头：

config.public_file_server.headers = {
  'Cache-Control' => 'public, max-age=0'
}

这会告诉浏览器每次请求都重新获取资源，避免本地缓存干扰。

总结 #

优先检查manifest.js的资产声明，删除预编译残留，清除Sprockets缓存，这是Rails 7.1开发环境资产实时更新最常见的修复点。若问题依旧，可尝试更新sprockets和listen gem到最新版本，或新建空白Rails 7.1应用对比配置差异。

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