Rails集成Turbo时出现link preload资源未使用警告咨询

问题根因 #

该警告和手动配置的preload标签无关，是Turbo默认资源加载逻辑和浏览器预加载校验规则的冲突导致：

• 带data-turbo-track="reload"属性的静态资源，会在Turbo驱动的页面跳转时被自动注入<link rel="preload">标签，用来提前拉取资源加快跳转渲染速度，这也是未手动写preload配置却出现相关标签的原因。
• 浏览器对预加载资源的使用校验绑定在传统整页刷新的window.load事件上，但Turbo页面跳转是PJAX局部替换，不会触发全量load事件，导致预加载拉取的CSS资源没在浏览器预设的校验窗口内被标记为“已使用”，从而抛出警告。
• 该警告仅为控制台提示，不会造成样式失效、页面报错等实际功能问题。
• 额外提示：当前layout中重复写了两个viewport meta标签，属于冗余配置，可直接删除其中一个，不影响本次警告修复。

解决方案 #

方案1：升级Turbo依赖（优先选择，无副作用） #

该问题属于Turbo的已知逻辑缺陷，在@hotwired/turbo-rails 7.3.0及以上稳定版本中已官方修复：新版本调整了预加载标签的注入逻辑，自动补全正确的as="style"属性，同时适配Turbo页面生命周期调整了资源标记时机，不会再触发浏览器校验警告。
操作步骤：

• 将package.json中@hotwired/turbo-rails的版本号更新为最新稳定版
• 执行包安装命令同步依赖：yarn install 或 npm install
• 重启Rails服务，浏览器硬刷新清除旧缓存后即可验证告警消失。

方案2：关闭CSS的Turbo追踪（适配无法升级依赖的场景） #

如果项目存在版本兼容问题无法升级Turbo，可直接关闭Turbo对CSS资源的自动追踪，从根源避免自动注入preload标签。
将application.html.erb中的样式表引入标签修改为：

<%= stylesheet_link_tag 'application', media: 'all', 'data-turbo-track': false %>

注意：该修改的副作用是静态资源版本更新时，Turbo跳转不会自动拉取最新CSS，需要用户触发整页刷新才能加载新样式，适合发布频率低、已有独立静态资源刷新机制的项目使用。

方案3：重写Turbo预加载逻辑（兼顾性能与告警消除） #

既不想升级依赖、又要保留Turbo资源追踪能力的场景，可以手动补丁修复预加载逻辑，在application.js中Turbo导入语句后添加如下代码：

import * as Turbo from "@hotwired/turbo-rails"

document.addEventListener("turbo:before-fetch-request", () => {
  document.querySelectorAll('link[rel="preload"][as="style"]').forEach(link => {
    link.addEventListener("load", () => {
      link.rel = "stylesheet"
    })
  })
})

验证注意事项 #

• 所有配置修改完成后，必须执行浏览器硬刷新（Windows: Ctrl+Shift+R，Mac: Cmd+Shift+R）清除旧资源缓存，避免缓存残留导致告警复现
• 开发环境若使用jsbundling/webpacker热重载，需重启编译进程，清除旧打包产物
• 生产环境部署后需同步刷新CDN节点上的静态资源缓存，确保用户拿到最新版本的资源文件

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