啟用跨來源隔離功能的指南

跨來源隔離可讓網頁使用 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. 設定報表功能，並設定網路伺服器來接收及儲存報表。
  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 屬性 (例如 <img src="example.jpg" crossorigin>)，確保已啟用 CORS。如果是 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，確認網頁已跨來源隔離。

資源