关于启用跨域隔离的指南

借助跨域隔离，网页可以使用 SharedArrayBuffer 等强大的功能。本文介绍了如何在网站上启用跨域隔离功能。

Eiji Kitamura

本指南介绍了如何启用跨域隔离。如果您想使用 SharedArrayBuffer、performance.measureUserAgentSpecificMemory() 或精确度更高的高分辨率计时器，则必须进行跨域隔离。

如果您打算启用跨域隔离，请评估这对您网站上的其他跨源资源（例如广告展示位置）的影响。

确定在您网站的哪些位置使用 SharedArrayBuffer
从 Chrome 92 开始，如果没有跨域隔离，使用 SharedArrayBuffer 的功能将无法正常运行。如果您因看到 SharedArrayBuffer 弃用消息而进入此页面，可能是因为您的网站或该网站上嵌入的某项资源正在使用 SharedArrayBuffer。为了确保您的网站不会因弃用而中断，请先确定它的使用位置。

如果您不确定在网站的什么位置使用 SharedArrayBuffer，可以通过以下两种方式确定：

  • 使用 Chrome 开发者工具
  • （高级）使用弃用报告

如果您已知道在哪里使用 SharedArrayBuffer，请跳转至分析跨域隔离的影响。

使用 Chrome 开发者工具

Chrome 开发者工具可让开发者检查网站。

  1. 在您怀疑可能正在使用 SharedArrayBuffer 的网页上打开 Chrome 开发者工具。
  2. 选择控制台面板。
  3. 如果网页使用的是 SharedArrayBuffer，系统会显示以下消息：
    [Deprecation] SharedArrayBuffer will require cross-origin isolation as of M92, around May 2021. See https://developer.chrome.com/blog/enabling-shared-array-buffer/ for more details. common-bundle.js:535
  4. 消息末尾的文件名和行号（例如 common-bundle.js:535）表示 SharedArrayBuffer 的来源。如果是第三方库，请与开发者联系来解决问题。如果此机制是在您的网站中实现的，请按照以下指南启用跨域隔离。
在未进行跨域隔离的情况下使用 SharedArrayBuffer 时，DevToools 控制台发出警告
在未进行跨域隔离的情况下使用 SharedArrayBuffer 时，DevToools 控制台发出警告。

（高级）使用弃用报告

某些浏览器具有弃用 API 在指定端点的报告功能。

  1. 设置弃用报告服务器并获取报告网址。为此，您可以使用公共服务或自行构建。
  2. 使用该网址，将以下 HTTP 标头设置为可能会传送 SharedArrayBuffer 的网页。
    Report-To: {"group":"default","max_age":86400,"endpoints":[{"url":"THE_DEPRECATION_ENDPOINT_URL"}]}
  3. 标头开始传播后，您注册的端点应该开始收集弃用报告。

如需查看实现示例，请访问：https://cross-origin-isolation.glitch.me。

分析跨域隔离的影响

如果能够评估启用跨域隔离对网站的影响而又不会真正造成任何破坏，那该有多好？借助 Cross-Origin-Opener-Policy-Report-Only 和 Cross-Origin-Embedder-Policy-Report-Only HTTP 标头，您可以做到这一点。

  1. 对顶级文档设置 Cross-Origin-Opener-Policy-Report-Only: same-origin。顾名思义，此标头仅会报告 COOP: same-origin 将对您的网站造成的影响，而不会停用与弹出式窗口的通信。
  2. 设置报告并配置 Web 服务器，以接收和保存报告。
  3. 对顶级文档设置 Cross-Origin-Embedder-Policy-Report-Only: require-corp。同样，通过此标头，您可以了解启用 COEP: require-corp 的影响，同时还能确保网站正常运行。您可以配置此标头，将报告发送到您在上一步中设置的同一报告服务器。

减轻跨域隔离的影响

确定哪些资源将受跨域隔离的影响后，请遵循以下一般准则，了解如何实际选择启用这些跨源资源：

  1. 在图片、脚本、样式表、iframe 等跨源资源中，请设置 Cross-Origin-Resource-Policy: cross-origin 标头。在同一网站资源上，设置 Cross-Origin-Resource-Policy: same-site 标头。
  2. 对于可使用 CORS 加载的资源，请确保已启用 CORS，具体方法是在相应的 HTML 标记中设置 crossorigin 属性（例如 <img src="example.jpg" crossorigin>）。对于 JavaScript 提取请求，请确保将 request.mode 设置为 cors。
  3. 如果您想在已加载的 iframe 中使用 SharedArrayBuffer 等强大功能，请将 allow="cross-origin-isolated" 附加到 <iframe>。
  4. 如果加载到 iframe 或工作器脚本的跨源资源涉及另一层 iframe 或工作器脚本，请以递归方式应用本部分中介绍的步骤，然后再继续。
  5. 确认所有跨源资源都选择启用后，请在 iframe 和工作器脚本上设置 Cross-Origin-Embedder-Policy: require-corp 标头（无论是同源还是跨源，这都是必需的）。
  6. 确保没有需要通过 postMessage() 进行通信的跨源弹出式窗口。启用跨域隔离后，您将无法让这些控件正常运行。您可以将通信移至未跨源隔离的其他文档，或者使用其他通信方法（例如 HTTP 请求）。

启用跨域隔离

在减轻了跨域隔离的影响后，请按照以下一般准则来启用跨域隔离：

  1. 在顶级文档上设置 Cross-Origin-Opener-Policy: same-origin 标头。如果您已设置 Cross-Origin-Opener-Policy-Report-Only: same-origin，请将其替换。这会阻止顶级文档与其弹出式窗口之间的通信。
  2. 在顶级文档上设置 Cross-Origin-Embedder-Policy: require-corp 标头。如果您已设置 Cross-Origin-Embedder-Policy-Report-Only: require-corp，请将其替换。此操作将阻止加载未选择启用的跨源资源。
  3. 检查 self.crossOriginIsolated 是否在控制台中返回 true，以验证您的页面是否已经过跨域隔离。

资源