废弃卸载事件

Demián Renzulli

Barry Pollard

发布时间：2023 年 8 月 10 日；上次更新时间：2025 年 6 月 23 日

我们将逐步更改默认设置，以逐步弃用 unload 事件，这样一来，除非网页明确选择重新启用 unload 处理脚本，否则网页将停止触发 unload 处理脚本。

弃用时间表

我们在 2019 年 1 月宣布打算实现返回/前进缓存时就指出，卸载行为最早可能会发生变化。在实施工作的同时，我们还开展了广泛的宣传活动，这使得卸载用量大幅下降。为了进一步扩大宣传范围，我们还开始提供一些方法来测试从 Chrome 115 弃用卸载功能的影响：

• 在 Chrome 115（2023 年 7 月）中使用 Permission-Policy API 进行卸载的公开测试
• 在 Chrome 117 中启用标志进行本地测试（2023 年 9 月）

在 2024 年，我们解决了阻碍该功能开始推出的几个问题。

以下是 unload 事件的当前弃用时间表：

完成前 50 个网站的发布后，我们会暂停并让其在一个或两个里程碑周期内进行过渡，然后在接下来的 8 个里程碑周期（大约 32 周）内获得进一步批准，以便将其推广到所有来源，大致如下所示：

请注意，如果此弃用时间表无法提供足够的时间来从卸载迁移，我们还提供了停用选项菜单。我们的目标是通过此软弃用来确定最后一个阶段（弃用卸载）的时间表，在此阶段我们将移除或减少这些停用选项。

背景

unload 旨在在文档卸载时触发。从理论上讲，它可用于在用户离开网页时运行代码，或用作会话结束回调。

此事件最常见的使用场景包括：

• 保存用户数据：请先保存数据，然后再离开此页面。
• 执行清理任务：在放弃网页之前关闭打开的资源。
• 发送分析数据：在会话结束时发送与用户互动相关的数据。

不过，unload 事件极其不可靠。

在桌面版 Chrome 和 Firefox 中，unload 相当可靠，但会阻止使用 bfcache（往返缓存），从而对网站性能产生负面影响。

在移动浏览器中，unload 通常不会运行，因为标签页经常会进入后台，然后被终止。因此，浏览器会选择优先使用移动设备上的 bfcache，而不是 unload，这使得它们变得更加不可靠。Safari 在桌面设备上也采用了这种行为。

Chrome 团队认为，在桌面设备上采用移动设备模式（即优先使用 bfcache 而非 unload）会使其在桌面设备上也变得更加不可靠，这会造成干扰，因为之前在 Chrome（和 Firefox）中，这种模式的表现相当可靠。相反，Chrome 的目标是彻底移除 unload 事件。在此之前，对于明确选择停用此功能的用户，该功能仍可在桌面设备上正常使用。

为何弃用 unload 事件？

弃用 unload 是我们在更大范围内认识当今网络的重要一步。unload 事件会让人误以为可以控制应用生命周期，但这与我们在现代计算世界中浏览网页的方式越来越不符。

移动操作系统会频繁冻结或卸载网页以节省内存，桌面浏览器现在也越来越多地出于同样的原因这样做。即使没有操作系统干预，用户自己也经常切换标签页并终止旧标签页，而无需正式“离开网页”。

移除已废弃的 unload 事件，是为了表明我们 Web 开发者需要确保我们的范式与现实世界相符，而不是依赖于已过时且不再适用的概念（如果它们曾经适用的话）。

unload 事件的替代方案

建议改用以下方法，而不是 unload：

• visibilitychange：用于确定网页的公开范围何时发生变化。当用户切换标签页、最小化浏览器窗口或打开新页面时，就会发生此事件。将 hidden 状态视为保存应用和用户数据的最后可靠时间。
• pagehide：用于确定用户何时离开了页面。当用户离开页面、重新加载页面或关闭浏览器窗口时，就会发生此事件。当网页最小化或切换到其他标签页时，系统不会触发 pagehide 事件。请注意，由于 pagehide 不会使网页不符合使用返回/前进缓存的条件，因此网页可能会在此事件触发后恢复。如果您要清理此事件中的任何资源，则可能需要在恢复网页时恢复这些资源。

beforeunload 事件的用例与 unload 略有不同，因为它是一个可取消的事件。它通常用于在用户离开时提醒用户未保存的更改。此事件也不可靠，因为如果后台标签页被终止，系统不会触发此事件。建议限制使用 beforeunload，仅在有条件时添加。而是改为针对大多数 unload 替换项使用前面提到的事件。

如需了解详情，请参阅有关绝不使用 unload 处理程序的建议。

检测 unload 的使用情况

您可以使用不同的工具来查找网页上 unload 事件的出现情况。这样，网站就可以发现自己是否在使用此事件（在自己的代码中或使用库），以及是否可能会受到即将弃用的事件的影响。

Chrome DevTools

Chrome 开发者工具包含 back-forward-cache 审核，可帮助您找出可能导致网页不符合往返缓存条件的问题，包括 unload 处理程序的使用情况。

如需测试返回/前进缓存，请按以下步骤操作：

1. 在网页上，打开开发者工具，然后依次前往应用 > 后台服务 > 前进/后退缓存。

2. 点击测试前进/后退缓存，Chrome 会自动将您定向到 chrome://terms/，然后返回到您的网页。或者，您也可以点击浏览器的“后退”和“前进”按钮。

如果您的网页不符合往返缓存条件，往返缓存标签页会显示一系列问题。在可执行下，您可以查看自己是否在使用 unload：

Reporting API

Reporting API 可与只读权限政策结合使用，以检测网站用户对 unload 的使用情况。

如需了解详情，请参阅使用 Reporting API 查找卸载

Bfcache notRestoredReasons API

添加到 PerformanceNavigationTiming 类中的 notRestoredReasons 属性会报告有关文档是否被阻止在导航时使用 bfcache 以及原因的信息。以下示例展示了现有 unload 监听器的响应对象警告的外观：

{
   children: [],
   id: null,
   name: null,
   reasons: [
     {"reason", "unload-listener"}
   ],
   src: null,
   url: "https://www.example.com/page/"
}

控制对 unload 的访问权限

Chrome 将逐步弃用 unload 事件。在此期间，您可以使用不同的工具来控制此行为，并为即将弃用做好准备。请注意，您不应长期依赖这些技术，而应尽快规划迁移到替代方案。

您可以使用以下选项启用或停用 unload 处理脚本，以测试在没有这些处理脚本的情况下您的网站会如何运行，以便为即将弃用做好准备。政策有不同的类型：

• 权限政策：这是一个平台 API，可供网站所有者使用 HTTP 标头在网站一级或单个网页一级控制对功能的访问权限。
• 企业版政策：供 IT 管理员为其组织或企业配置 Chrome 的工具。您可以使用管理控制台（例如 Google 管理控制台）进行配置。
• Chrome 标志：这让单个开发者可以更改 unload 弃用设置，以测试对各种网站的影响。

“权限”政策

从 Chrome 115 开始，我们添加了权限政策，以允许网站选择停用 unload 处理脚本，并立即受益于 bfcache 以提升网站性能。请参阅有关如何为您的网站设置此参数的示例。这样，网站就可以在 unload 弃用之前做好准备。

Chrome 117 中将延长此期限，以允许网站执行相反操作，并选择继续尝试触发 unload 处理脚本，因为 Chrome 将在未来将默认值更改为不触发这些脚本。请参阅有关如何继续允许为您的网站触发卸载处理脚本的示例。此选择不会永久保留，应用于为网站留出从 unload 处理程序迁移的时间。

企业政策

如果企业的软件需要 unload 事件才能正常运行，则可以使用 ForcePermissionPolicyUnloadDefaultEnabled 政策来阻止其控制的设备逐步弃用该事件。启用此政策后，unload 将继续默认为所有来源启用。网页仍可根据需要设置更严格的政策。与停用权限政策一样，这是一种用于缓解潜在破坏性更改的工具，但不应无限期使用。

Chrome 标志和命令行开关

除了企业政策之外，您还可以使用 Chrome 标志和命令行开关为个别用户停用弃用功能：

将 chrome://flags/#deprecate-unload 此设置设为 enabled 会提前采用默认的废弃设置，并阻止 unload 处理脚本触发。您仍然可以使用“权限”政策逐个网站地替换这些事件，但默认情况下，这些事件会继续触发。

这些设置还可以通过命令行开关进行控制。

选项比较

下表总结了之前讨论的选项的不同用途：

总结

unload 处理脚本即将被弃用。这些监听器长期以来一直不可靠，无法保证在所有文档被销毁的情况下都会触发。此外，unload 处理脚本与 bfcache 不兼容。

使用 unload 处理程序的网站应为即将弃用 unload 处理程序做好准备，具体方法包括测试是否存在任何现有 unload 处理程序、移除或迁移这些处理程序，或者在需要更多时间时，作为最后的手段推迟弃用。

致谢

感谢 Kenji Baheux、Fergal Daly、Adriana Jara 和 Jeremy Wagner 帮助审核本文。

主打图片：Unsplash 上的 Anja Bauermann