coi-serviceworker避坑清单:为什么脚本不能打包进Bundle或托管到CDN
coi-serviceworker避坑清单:为什么脚本不能打包进Bundle或托管到CDN
如果你需要跨源隔离(Cross-Origin Isolation)却改不了服务器响应头,coi-serviceworker 就是为此而生的:它通过一个 Service Worker 拦截页面请求,自动注入 COOP 和 COEP 响应头,让 GitHub Pages 这类静态托管也能开启 crossOriginIsolated。但很多新手一上来就犯两个错误——把脚本打包进 Bundle 或 从 CDN 引用,结果功能静默失效。本文用一份避坑清单讲清楚为什么,以及正确的安装姿势。
先搞懂:跨源隔离(COOP 与 COEP)能解决什么
当 window.crossOriginIsolated 为 true 时,你才能解锁这些高级能力:
- SharedArrayBuffer:JavaScript 与 WebAssembly 线程间共享内存
- WebAssembly 多线程:
atomics.wait、atomics.notify等原语 - 更高性能:WASM 应用(如 3D 引擎、视频解码、编译工具链)可多线程并行
在服务器端,你需要发送 Cross-Origin-Opener-Policy: same-origin 和 Cross-Origin-Embedder-Policy: require-corp(或 credentialless)两个响应头才能达成隔离。但对于静态站点托管(GitHub Pages、S3 静态站等),你没有权限修改响应头——这正是 coi-serviceworker 的价值:用一个 Service Worker 在客户端"补上"这些头。
避坑一:脚本不能打包进 Bundle
README 第一条规则写得很直白(见 README.md):
It must be in a separate file, you can't bundle it along with your app.
原因:脚本注册 Service Worker 时使用的来源路径是:
n.serviceWorker.register(window.document.currentScript.src)
document.currentScript 只有在独立 <script src="..."> 标签加载时才有值。如果你用 webpack、Vite 等把脚本内容打进 bundle.js,currentScript.src 就会指向你的 bundle 文件,导致:
- 浏览器把你的整个应用 bundle 当作 Service Worker 来执行,注册直接失败
- 即使侥幸注册成功,Worker 的作用域(scope)也错了,请求拦截逻辑完全乱套
正确做法:让打包器把它当作"原样输出的静态资源",例如 npm 安装后拷贝到产物目录:
npm i --save coi-serviceworker
cp node_modules/coi-serviceworker/coi-serviceworker.js dist/
避坑二:脚本不能托管到 CDN
第二条规则:
It can't be loaded from a CDN: it must be served from your own origin.
原因:Service Worker 受浏览器同源策略强约束——只能注册来自当前页面同源(same-origin)的文件。从 cdn.xxx.com 加载的脚本,其 URL 与你页面不同源,注册时浏览器会直接抛错。
此外还有更深层的原因:这个 Worker 需要改写你站点所有响应的头信息(见 coi-serviceworker.js 中的 fetch 拦截逻辑),跨源 CDN 上的 Worker 根本没有权限这样做。
正确做法:把 coi-serviceworker.js(或压缩版 coi-serviceworker.min.js)下载到你的项目里,放在 index 文件同级或上级的任意目录,例如:
my-site/
├── index.html
└── coi-serviceworker.js ← 必须同源的独立文件
避坑三:必须运行在安全上下文
第三条规则:
Your page will still need to be either served from HTTPS, or served from localhost.
Service Worker 本身只能在安全上下文(secure context)中注册。本地开发用 localhost 没问题,线上环境必须启用 HTTPS。另外注意:部分浏览器(如 Firefox 隐私模式)可能不暴露 navigator.serviceWorker,脚本会静默放弃注册(见 coi-serviceworker.js)。
三步快速安装:正确姿势一览
以仓库中的 index.html 为参考,完整流程如下:
- 下载
coi-serviceworker.js(或coi-serviceworker.min.js) - 放置在与 index 文件同级或上级的目录(保证同源)
- 引用:在 HTML 中加入一行
<script src="coi-serviceworker.js"></script>
首次访问时页面会自动刷新一次,让 Service Worker 接管页面——这是预期行为,不是 bug 😄。之后每次访问都无需再刷新。
进阶:用全局 coi 变量定制行为
默认行为之外,你可以在页面中定义全局变量 window.coi 来控制脚本(见 README.md):
| 配置项 | 作用 | 常见场景 |
|---|---|---|
shouldRegister |
决定是否注册 SW | 用 !reloadedBySelf 避免无限刷新循环 |
shouldDeregister |
是否注销已有 SW | 给用户提供"关闭隔离"开关 |
coepCredentialless |
是否优先用 credentialless |
提升第三方资源兼容性 |
coepDegrade |
credentialless 失败后是否降级回 require-corp |
自动兜底 |
doReload |
自定义刷新逻辑 | 先弹窗提示用户"点击确定刷新以启用功能" |
quiet |
是否静默 | 生产环境关掉控制台日志 |
比如想让刷新更友好:
window.coi = {
doReload: () => {
alert("点击确定刷新页面,以启用跨源隔离功能");
window.location.reload();
}
};
验证:一行确认 crossOriginIsolated 已生效
刷新后打开浏览器控制台,输入:
window.crossOriginIsolated // 期望输出 true
如果为 true,说明 COOP/COEP 头已成功注入,SharedArrayBuffer 和 WASM 多线程可以正常工作。参考 index.html 中的检测写法,你也可以在页面里直接展示 ✅/❌ 状态。
常见坑速查表
| ❌ 错误操作 | 现象 | ✅ 正确做法 |
|---|---|---|
| 打包进 bundle.js | SW 注册失败或作用域错误 | 作为独立文件输出到 dist |
<script src="https://cdn.../coi-serviceworker.js"> |
注册被浏览器拒绝 | 下载到站点内同源目录 |
| HTTP 环境引用 | 静默不注册(安全上下文缺失) | 上 HTTPS 或用 localhost |
| 首次访问"莫名其妙"刷新 | 正常现象 | 可用 doReload 提示用户 |
| 隐私模式下不生效 | 无法注册 SW | 属于浏览器限制,可接受 |
一句话总结:coi-serviceworker 的三条铁律——独立文件、同源托管、安全上下文——都源于 Service Worker 的浏览器安全模型。记住"它必须是你自己站点上的一个独立 .js 文件",就避开了 90% 的坑。更多用法细节可查看 README.md 与核心实现 coi-serviceworker.js。