关于启用跨域隔离的指南

跨域隔离功能可让网页使用 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  for more details. common-bundle.js:535
  4. 消息末尾的文件名和行号（例如 common-bundle.js:535) 表示 SharedArrayBuffer 的来源。如果是第三方库， 请与开发者联系以解决问题。如果是作为网站的一部分实现的，请按照 以下指南启用跨域隔离功能。
在未使用跨源隔离的情况下使用 SharedArrayBuffer 时，开发者工具控制台会显示警告。
在未使用跨域隔离的情况下使用 SharedArrayBuffer 时，开发者工具控制台会显示警告。

（高级）使用弃用报告

部分浏览器具有 将弃用 API 报告给指定端点的报告功能。

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

请参阅实现示例。

分析跨域隔离的影响

如果您可以在不实际破坏任何内容的情况下评估启用跨域隔离功能对网站的影响，那岂不是很好？您可以使用 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 加载的资源，请确保通过在其 HTML 标记中设置 crossorigin 属性来启用 CORS（例如 <img src="example.jpg" crossorigin>）。对于 JavaScript 提取请求，请确保 request.mode 设置为 cors。
  3. 如果您想在 加载的 iframe 中使用 SharedArrayBuffer 等强大功能，请将 allow="cross-origin-isolated" 附加到 <iframe>。
  4. 如果加载到 iframe 或 Worker 脚本中的跨域资源涉及另一层 iframe 或 Worker 脚本，请先以递归方式应用本部分中所述的步骤，然后再继续。
  5. 确认所有跨域资源都已选择启用后，在 iframe 和 Worker 脚本中设置 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，以验证网页是否已进行跨域隔离。

资源