Rails 7使用data-turbo-track: 'reload'时页面重复加载问题

问题场景 #

使用Rails 7搭配Importmap开发时，在视图中通过以下代码引入脚本：

<% content_for :head do %>
  <%= javascript_include_tag 'path/to/script', 'data-turbo-track': 'reload' %>
<% end %>

原本期望脚本仅在当前页面执行，但出现两类异常：

• 带data-turbo-track: 'reload'属性时：进入该页面会触发页面两次加载（脚本仅执行一次）；离开后首次进入其他页面，同样会触发两次加载（脚本再次执行一次）
• 移除该属性后：首次进入页面脚本不执行，但后续所有页面都会执行脚本，且无重复加载，脚本会一直存在直到手动刷新页面（F5）

附脚本代码：

$(document).on("turbo:load", () => {
    alert("test");
});

原因解析 #

1. 带data-turbo-track: 'reload'时的重复加载 #

Turbo的data-turbo-track="reload"核心作用是对比前后页面的head资源，若资源有新增/移除/变化，则触发全页面刷新：

• 进入目标页面时：Turbo通过AJAX加载页面后，发现新页面的head多了这个脚本标签，判定资源变更，随即触发一次全页面刷新，所以你看到“加载两次”——第一次是Turbo的无刷新导航，第二次是强制全刷新。
• 离开该页面进入其他页面时：Turbo又检测到head中少了这个脚本标签，再次判定资源变更，触发全页面刷新；刷新后turbo:load事件触发，脚本绑定的回调会执行一次。

2. 移除data-turbo-track后的脚本残留 #

Importmap会将通过javascript_include_tag引入的脚本加载到全局JS环境，而Turbo的页面切换是AJAX无刷新导航，不会重置全局上下文：

• 首次进入页面时：脚本是在Turbo完成页面加载（turbo:load事件已触发）后才插入head的，所以脚本里的监听函数错过了执行时机。
• 后续页面切换时：脚本已存在于全局环境，每次turbo:load事件触发，绑定的回调都会执行，直到手动刷新页面重置JS环境。

解决方案 #

若要实现脚本仅在特定页面执行，推荐以下符合Rails 7生态的做法：

方案一：模块导入+一次性事件监听 #

1. 在Importmap中注册脚本模块：

   # config/importmap.rb
   pin "path/to/script", to: "path/to/script.js"
   

2. 在目标页面的content_for :head中导入并绑定一次性事件：

   <% content_for :head do %>
     <script type="module">
       import "./path/to/script.js";
       // 绑定一次性turbo:load监听
       const handler = () => {
         alert("test");
         document.removeEventListener("turbo:load", handler);
       };
       document.addEventListener("turbo:load", handler);
       // 页面切换前清理监听，防止残留
       document.addEventListener("turbo:before-cache", () => {
         document.removeEventListener("turbo:load", handler);
       });
     </script>
   <% end %>
   

方案二：使用Stimulus控制器（推荐） #

Rails 7默认集成Stimulus，适合实现页面级的隔离逻辑：

1. 创建Stimulus控制器：

   // app/javascript/controllers/test_controller.js
   import { Controller } from "@hotwired/stimulus"
   
   export default class extends Controller {
     // 页面加载完成并挂载控制器时执行
     connect() {
       alert("test");
     }
   
     // 页面切换前清理资源
     disconnect() {
       // 若有需要，添加清理逻辑
     }
   }
   

2. 在目标页面视图中挂载控制器：

   <div data-controller="test"></div>
   

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