Linux Nginx 配置 COOP 和 COEP：让 SharedArrayBuffer 可用前先做这 4 项检查

页面里已经写了 SharedArrayBuffer，本地开发跑着完全正常，一上线到 Linux 服务器，浏览器还是提示 SharedArrayBuffer 不可用，常见问题根本不出在 JavaScript 逻辑，全是响应头配置没到位。浏览器要求页面进入跨源隔离状态，Nginx 少配一个头、CDN 上某张图片没开对应 CORS，都会让这个状态没法正常建立。

为什么只写 SharedArrayBuffer 还不够

SharedArrayBuffer、更高精度的计时能力等接口，都需要浏览器确认当前文档处在跨源隔离环境。这个状态不是前端随便改个变量就能开关的，是浏览器根据顶层文档的 COOP、COEP 以及所有资源的加载结果综合判断的。最直接的检查方式是打开线上页面控制台：

console.log(self.crossOriginIsolated)
// true 才表示当前页面已进入跨源隔离状态

返回 false 时，先别急着改业务逻辑。先确认线上返回的 HTML 是否真的带上了对应响应头，再看 Network 面板里有没有被 COEP 拦截的第三方资源。很多人排查卡在这里：配置已经写进 Nginx 文件，但实际请求是被 CDN、其他反向代理 server 块或者旧缓存版本处理的，新配置根本没生效。

Linux 上先把 Nginx 响应头配对

如果目标是让单个独立页面进入跨源隔离，可以从该页面所在的 location 开始调整。下面的示例适合静态站点或者由 Nginx 反代的前端入口；always 能让错误响应也带上这两个头，排查问题的时候更方便。

server {
    listen 443 ssl;
    server_name app.example.com;

    location /wasm-lab/ {
        add_header Cross-Origin-Opener-Policy "same-origin" always;
        add_header Cross-Origin-Embedder-Policy "require-corp" always;
        try_files $uri $uri/ /wasm-lab/index.html;
    }
}

改完先校验配置语法，再平滑重载配置。生产环境我更建议把这两步连到变更流程里，不要只靠后台面板提示保存成功就认定生效。

sudo nginx -t
sudo systemctl reload nginx
curl -I https://app.example.com/wasm-lab/

COEP 最容易拦住哪些资源

COEP 的难点根本不是配头，而是清点全量依赖资源清单。页面启用 require-corp 后，跨域资源必须通过 CORS 或 CORP 明确获得加载授权。经常被遗漏的资源包括第三方字体、自建或第三方图片 CDN、埋点统计脚本、嵌入式客服组件、地图组件和各类 iframe。

先用浏览器 Network 面板筛选所有失败请求，再按资源归属分类处理。自己控制的 CDN 可以补配合适的 CORS 或 CORP 头；第三方资源如果没法提供对应授权，就要改成同源托管、替换对应服务商，或者把使用该资源的页面留在未开启隔离的区域。不存在能“强行兼容”所有资源的万能 Nginx 配置。

crossorigin 不是绕过策略的特殊按钮。如果资源服务端没有给出对应 CORS 响应，它只会让问题更早暴露出来。对 iframe 还要格外留意：文档嵌套链路通常也需要满足隔离条件，带登录流程、支付或跨站通信的窗口一定要在灰度环境里实际测试。

用独立路径灰度，比全站加头稳得多

COOP 会改变页面与弹窗的浏览上下文关系，COEP 会改变所有子资源的加载规则。直接在站点根路径加头，最容易误伤已经稳定运行的登录、广告、客服或数据看板功能。更稳妥的落地顺序是：

1. 把依赖 SharedArrayBuffer 的功能放到独立路径，例如 /wasm-lab/。
2. 列出该路径实际请求的所有脚本、字体、图片、Worker 和 iframe。
3. 在测试域名加入 COOP、COEP 头，记录被阻止的资源和对应的处置方案。
4. 用真实账号登录、调起弹窗、下载资源和主流移动端浏览器完成回归后，再逐步扩大覆盖范围。

如果你不得不保留跨域弹窗通信，不要默认 same-origin 能无缝兼容旧逻辑。先确认业务到底依赖 window.opener、postMessage 还是后端回调通信，再决定隔离页面是否需要拆到独立入口。这个取舍比“头有没有配对”更关键。

验收时不要只看响应头

下面四项都通过，才说明配置真正落地：

curl -sI https://app.example.com/wasm-lab/ | \
  rg 'Cross-Origin-(Opener|Embedder)-Policy'

# 浏览器控制台
self.crossOriginIsolated
typeof SharedArrayBuffer

• curl -I 能看到两个目标响应头，而不是只在本机配置文件里存在。
• self.crossOriginIsolated 为 true。
• Network 面板没有被 COEP 阻断后悄悄降级的关键脚本、字体或 iframe。
• 登录弹窗、授权回跳和需要跨窗口通信的路径已经完成回归测试。

相关问题

只设置 COOP 能启用 SharedArrayBuffer 吗？

通常不行。跨源隔离需要 COOP 与 COEP 同时满足对应条件；只加一个头不会拿到目标隔离状态。

能把 COEP 写成 credentialless 吗？

浏览器和不同资源类型的实际行为需要按你的依赖链路验证。如果现有方案已经能通过 CORS 或 CORP 完成授权，优先用可解释、可回溯的配置，不要在没有测试的情况下随意替换策略。

为什么 curl 看到了头，控制台还是 false？

可能请求的不是顶层文档、缓存还在返回旧版 HTML，或是页面加载了不符合 COEP 条件的跨域资源。用 Network 面板确认文档响应和失败资源，比只看单条 curl 输出更可靠。

服务端渲染页面也能这么配置吗？

可以，关键是最终返回的顶层 HTML 响应带上合适的头，并且它实际加载的所有资源都满足策略要求。配置位置可以放在 Nginx，也可以放在应用层，但不要两边给出互相矛盾的头值。

收尾检查

跨源隔离不是给 Nginx 加两行头就结束的小改动。把线上响应、资源依赖、浏览器状态和关键业务流程一起纳入验收，才能正常用上需要的浏览器能力，也不会把原有页面悄悄推入不可用的异常状态。