跳转到主要内容
OneSignal service worker（OneSignalSDKWorker.js）是托管在您服务器上的 JavaScript 文件，是网页推送通知的必要组件。它使您的网站能够接收和显示通知，即使用户不在您的页面上也能正常运行。
Diagram showing the OneSignal service worker receiving a push event and displaying a notification
如果您使用我们的 WordPress 插件，service worker 会自动添加。请跳过本指南并返回 WordPress 设置。

​
Service worker 设置

为 OneSignal 推送通知创建专用的 OneSignalSDKWorker.js 文件。如果您的网站已有 service worker 并希望使用单个文件，请改为参阅合并多个 service worker。
1

下载或创建 OneSignalSDKWorker.js

在 Web SDK 设置过程中从 OneSignal 仪表板下载该文件，或从 GitHub 下载。或者，创建一个名为 OneSignalSDKWorker.js 的文件，包含以下单行代码：
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
如有需要，您可以重命名该文件（例如改为 onesignalsdkworker.js）。如果这样做，只需将本指南中的 OneSignalSDKWorker.js 替换为您的文件名即可。
2

上传到您的 Web 服务器

将 OneSignalSDKWorker.js 放置在服务器上，使其可通过 HTTPS 公开访问。该文件不得要求身份验证或登录才能访问。推荐方式： 将文件托管在永远不会提供页面的专用子目录中，例如 /push/onesignal/。这样可以避免与网站上其他 service worker 发生冲突（例如 PWA 或 AMP service worker），并保持 URL 路径稳定。
  • 示例：https://yoursite.com/push/onesignal/OneSignalSDKWorker.js
替代方式： OneSignal Web SDK 默认在网站根目录查找该文件（https://yoursite.com/OneSignalSDKWorker.js）。您可以将文件上传到根目录，但可能与其他需要根作用域的 service worker 发生冲突。例如，如果您使用 PWA，请将 OneSignalSDKWorker.js 放在子目录中。
请选择永久的 URL 路径。一旦浏览器在给定 URL 注册了 service worker，更改该 URL 需要进行迁移。
3

验证文件可访问性

在浏览器中导航到文件 URL（例如 https://yoursite.com/push/onesignal/OneSignalSDKWorker.js）。您应该看到第 1 步中的 importScripts 行：
Browser displaying the single importScripts line inside OneSignalSDKWorker.js
如果您看到 404 错误、空白页面或登录提示，则说明文件未正确上传或位于身份验证之后。
4

配置 SDK 路径（仅限子目录）

如果您将文件放置在网站根目录，则无需额外配置——直接跳到下一步。如果您将文件放置在子目录中，请告知 SDK 文件位置：

​
典型网站设置

  1. 在 OneSignal 仪表板中，进入设置 > Push & In-App > Web 设置。
  2. 在高级推送设置下，启用自定义 service worker 路径和文件名。
OneSignal dashboard fields for service worker path, filename, and registration scope
字段说明示例
Path to service worker files托管 OneSignalSDKWorker.js 的目录。/push/onesignal/
Service worker filename.js 文件的名称。OneSignalSDKWorker.js
Service worker registration scopeservice worker 控制的 URL 路径。必须位于文件托管目录或其子目录。请使用永远不会提供用户页面的路径。/push/onesignal/

​
自定义代码设置

在您的 OneSignal.init() 调用中传入 serviceWorkerPath 和 serviceWorkerParam：
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  window.OneSignalDeferred.push(async function(OneSignal) {
    await OneSignal.init({
      appId: "YOUR_APP_ID",
      serviceWorkerPath: "push/onesignal/OneSignalSDKWorker.js",
      serviceWorkerParam: { scope: "/push/onesignal/" },
    });
  });
</script>
参数说明示例
serviceWorkerPath从网站根目录到 .js 文件的相对路径（不含开头斜杠）。"push/onesignal/OneSignalSDKWorker.js"
serviceWorkerParam.scopeservice worker 控制的 URL 路径。必须位于文件托管目录或其子目录。请使用永远不会提供用户页面的路径。"/push/onesignal/"
5

查看 service worker 要求

OneSignalSDKWorker.js 文件必须满足以下所有要求。如有任何要求未满足，推送通知将无法正常工作。
要求详情
可公开访问在浏览器中导航到文件 URL，确认可以看到 JavaScript 代码。
正确的内容类型服务器必须返回 Content-Type: application/javascript; charset=utf-8。
同源文件必须托管在与您网站相同的域名上。不允许使用 CDN 和子域名。请参阅 MDN：注册您的 worker。
HTTPSService worker 需要安全上下文。开发期间 localhost 是唯一的例外。
Service worker 设置完成。

Web SDK 设置

继续使用 Web SDK 设置指南了解后续步骤。

​
合并多个 service worker

网站上的每个 service worker 文件都注册在一个作用域——一个决定其控制哪些页面的 URL 路径。在给定作用域只能有一个 service worker 处于活跃状态。如果您已经有一个 service worker（例如 PWA 或缓存 worker）并且希望 OneSignal 共享同一文件，可以将它们合并。
将 service worker 保存在具有独立作用域的独立文件中更易于维护且可避免冲突。仅当您的设置需要单个 service worker 文件时才进行合并。
若要合并，请将 OneSignal importScripts 行添加到您现有的 service worker 文件中： 
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
importScripts("https://yoursite.com/your-other-service-worker.js");
合并后，更新 OneSignal 配置以指向您现有的 service worker 文件。使用合并文件的路径和文件名，按照第 4 步：配置 SDK 路径进行操作。

​
迁移指南

本节适用于需要更改 service worker 文件路径、文件名或作用域的现有 OneSignal 客户。除非您有特定原因需要更改当前配置，否则请勿执行这些步骤。
迁移原因：
  • 根作用域 OneSignal service worker 与渐进式网页应用（PWA）冲突
  • Service worker 与 AMP 或其他缓存 service worker 冲突
  • 安全策略禁止在根作用域运行第三方 service worker 代码
选项 1：仅更改作用域（推荐）仅更改作用域是最安全的迁移方式。文件保持在当前 URL，现有订阅者可以不间断地继续接收通知。如果您的文件仅包含 OneSignal 代码确认 OneSignalSDKWorker.js 仅包含：
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
按照第 4 步：配置 SDK 路径中的描述，使用仪表板或 serviceWorkerParam 更新作用域。无需其他更改。
如果 OneSignalSDKWorker.js 今天没有托管在您的域名根目录，您必须继续使用 Service-Worker-Allowed 响应头在当前 URL 托管该文件至少一年。请在您的后端代码或内部文档中添加注释，以防文件被意外删除。
如果您的文件包含 OneSignal + 其他代码您的 service worker 可能包含额外的 importScripts 调用（例如，来自合并多个 service worker 指南）。如果您当前的设置仍然有效，请保持原样——拆分合并的 service worker 需要两阶段发布。如果您必须分离它们：
1

向现有文件添加保留注释

在当前 service worker 中 OneSignal importScripts 行的上方添加：
// KEEP until YYYY-MM-DD: Required for push delivery to subscribers who have not revisited.
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
日期至少设置为一年后。
2

创建新的专用 OneSignal service worker

在子目录（例如 /push/onesignal/）中创建仅包含以下内容的 OneSignalSDKWorker.js：
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
3

更新 OneSignal 配置

按照第 4 步：配置 SDK 路径中的描述，使用仪表板或 OneSignal.init() 设置新路径和作用域。
4

等待订阅者迁移

新访客和回访者会自动使用新的 service worker 进行注册。等待至少一年，让大多数现有订阅者重新访问您的网站。
5

清理

删除不活跃用户（超过您选择的保留期限的用户），然后从原始 service worker 文件中移除 OneSignal importScripts 行。
选项 2：更改文件名或文件位置更改文件名或目录更为复杂，因为浏览器从最初注册时的 URL 获取 service worker。尚未重新访问您网站的订阅者仍引用旧 URL。
您必须继续在旧 URL 托管原始文件至少一年。删除该文件会导致浏览器尝试更新 service worker 时出现 404 错误，受影响的订阅者将停止接收通知。
如果您的文件仅包含 OneSignal 代码
1

向旧文件添加保留注释

// KEEP until YYYY-MM-DD: Required for push delivery to subscribers still on the old service worker URL.
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
2

在新位置创建新文件

将 OneSignalSDKWorker.js（或您选择的文件名）放置在新目录中，包含：
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
3

更新 OneSignal 配置

按照第 4 步：配置 SDK 路径中的描述设置新路径、文件名和作用域。
4

等待订阅者迁移

新访客和回访者会自动使用新文件进行注册。等待至少一年。
5

清理

删除不活跃用户（超过您保留期限的用户），然后删除旧文件。
如果您的文件包含 OneSignal + 其他代码按照上方选项 1：仅更改作用域中的步骤操作。流程相同。

​
常见问题

​
为什么我的 service worker 返回 404？

文件不在 SDK 预期的 URL 位置。在浏览器中导航到完整的文件 URL 以确认其可访问性。如果您将文件放置在子目录中，请验证 serviceWorkerPath（自定义代码）或仪表板路径设置与实际文件位置匹配——包括目录和文件名。

​
为什么我移动 service worker 文件后通知不再显示？

现有订阅者仍然引用旧的 service worker URL。每次推送到达时，浏览器都会获取已注册的 URL（最多缓存 24 小时）。如果旧 URL 返回 404，这些订阅者将无法收到通知。继续托管旧文件至少一年，同时订阅者通过重新访问您的网站自然迁移。请参阅迁移指南和网页推送通知未显示指南。

​
我可以在 CDN 或子域名上托管 service worker 吗？

不可以。浏览器要求 service worker 与注册它的页面来自同一源。文件必须在您的主域名上——不能使用 CDN、子域名或不同域名。

​
为什么我的 PWA 与 OneSignal service worker 冲突？

两者可能都注册在根作用域（/），而在特定作用域只能注册一个 service worker。将 OneSignal service worker 移至子目录作用域（例如 /push/onesignal/），使您的 PWA 保留对根作用域的控制，或按照合并多个 service worker 中的描述合并 service worker。

​
我可以重命名 OneSignalSDKWorker.js 文件吗？

可以。如果您的服务器需要特定的命名规范（例如全小写），可以将文件重命名为 onesignalsdkworker.js 之类的名称。如果这样做，请在您的 OneSignal 配置中更新文件名——在仪表板的 Service worker filename 字段中，或在 OneSignal.init() 调用的 serviceWorkerPath 参数中。详情请参阅第 4 步。

​
我的服务器应该为 service worker 文件返回什么内容类型？

服务器必须返回 Content-Type: application/javascript; charset=utf-8。某些服务器或 CDN 配置可能返回不正确的 MIME 类型，导致浏览器拒绝 service worker 注册。