关于启用跨域隔离的指南

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

Eiji Kitamura

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

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

确定在您网站的哪些位置使用 SharedArrayBuffer

从 Chrome 92 开始，如果没有跨域隔离，使用 SharedArrayBuffer 的功能将无法正常运行。如果您因看到 SharedArrayBuffer 弃用消息而进入此页面，可能是因为您的网站或该网站上嵌入的某项资源正在使用 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 控制台发出警告。

（高级）使用弃用报告

某些浏览器具有弃用 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 的影响，同时还能确保网站正常运行。您可以配置此标头，将报告发送到您在上一步中设置的同一报告服务器。

注意 ：您还可以在 Chrome 开发者工具的“网络”面板中启用网域列，大致了解哪些资源将受到影响。

注意 ：启用跨域隔离将会阻止加载您未明确选择启用的跨源资源，并阻止顶级文档与弹出式窗口进行通信。我们一直在探索大规模部署Cross-Origin-Resource-Policy的方法，因为跨域隔离功能需要所有子资源明确选择启用。我们提出了相反的想法：一种新的 COEP“无凭据”模式，可以通过剥离所有凭据来加载没有 CORP 标头的资源。我们希望这样能够减轻您确保子资源发送 Cross-Origin-Resource-Policy 标头的负担。虽然 Chrome 96 版及更高版本支持 credentialless 模式，但任何其他浏览器尚不支持该模式，但这可能会导致一些开发者发现在此阶段部署 COOP 或 COEP 并非易事。此外，众所周知，Cross-Origin-Opener-Policy: same-origin 标头会破坏需要跨源窗口互动（例如 OAuth 和付款）的集成。为了缓解此问题，我们正在探索放宽条件，以便为 Cross-Origin-Opener-Policy: same-origin-allow-popups 启用跨域隔离。这样，就可以与自行打开的窗口进行通信。如果您想启用跨域隔离，但被这些验证所阻止，我们建议您注册源试用并等待新模式可用。在这些新模式推出之前，我们不打算终止源试用。

减轻跨域隔离的影响

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

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，以验证您的页面是否已经过跨域隔离。

由于简单的服务器不支持发送标头，因此在本地服务器上启用跨域隔离可能很麻烦。您可以使用命令行标记 --enable-features=SharedArrayBuffer 启动 Chrome，以便在不启用跨域隔离的情况下启用 SharedArrayBuffer。了解如何在相应平台上使用命令行 flag 运行 Chrome。

资源

• 使用 COOP 和 COEP 将网站设置为“跨域隔离”
• Android Chrome 88 和桌面版 Chrome 92 中的 SharedArrayBuffer 更新