> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Web SDK 故障排除
> 在 Chrome、Firefox、Safari 和 Android 上排除 OneSignal Web Push 问题。通过分步调试指导修复常见的 Service Worker、源、MIME 类型和移动推送错误。
## 概述
本指南将指导您排除 OneSignal Web SDK 设置的故障。在继续之前，请查看 [Web SDK 设置](./web-sdk-setup)以确保您已完成所有步骤。
Web 推送似乎不工作的最常见原因实际上与您的浏览器和设备的通知设置有关：
### 浏览器兼容性
用户可能会看到[网页权限提示](/docs/cn/permission-requests),但无法在隐身、隐私或访客浏览器模式下订阅推送通知。
| Browser | Windows | macOS | Android | iOS |
| -------------------------------------------------------------------------------- | ------- | ----- | ------- | --- |
| [Chrome](https://en.wikipedia.org/wiki/Google_Chrome) | ✅ | ✅ | ✅ | ✅ ¹ |
| [Firefox](https://en.wikipedia.org/wiki/Firefox) | ✅ | ✅ | ✅ | ✅ ¹ |
| [Safari 10+](https://en.wikipedia.org/wiki/Safari_\(web_browser\)) | ❌ | ✅ | ❌ | ✅ ¹ |
| [Microsoft Edge](https://en.wikipedia.org/wiki/Microsoft_Edge) | ✅ | ✅ | ✅ | ✅ ¹ |
| [Opera](https://en.wikipedia.org/wiki/Opera_\(web_browser\)) ² | ✅ | ✅ | ✅ | ✅ ¹ |
| [Samsung Internet](https://en.wikipedia.org/wiki/Samsung_Internet_for_Android) ² | ❌ | ❌ | ✅ | ✅ ¹ |
| [Yandex](https://en.wikipedia.org/wiki/Yandex_Browser) ² | ✅ | ✅ | ✅ | ✅ ¹ |
| [UC Browser](https://en.wikipedia.org/wiki/UC_Browser) ² | ✅ | ❌ | ✅ | ✅ ¹ |
| [Internet Explorer](https://en.wikipedia.org/wiki/Internet_Explorer) | ❌ | ❌ | ❌ | ❌ |
| [DuckDuckGo](https://en.wikipedia.org/wiki/DuckDuckGo) | ❌ | ❌ | ❌ | ❌ |
¹ iOS 需要安装 Web 应用(参见 [iOS 网页推送设置](/docs/cn/web-push-for-ios))
² 基于 Chromium 的浏览器在 OneSignal 分析中显示为 "Chrome"
### 设备通知设置
设备通知设置是Web推送通知无法显示的**最常见原因**。请在检查其他问题之前，先检查以下设置（包括勿扰模式、低电量等专注模式）。
请从下方标签页选择正确的操作系统。您应该看到 Windows、macOS、Android 和 iOS。
1. 选择**开始 > 设置 > 通知和操作 > 从应用和其他发送者获取通知**
2. **确保您的站点和浏览器也已启用。**
**Windows 11 通知设置:**
1. 选择**开始 > 设置 > 系统 > 通知**
2. 打开**通知**
3. 关闭**勿扰模式**（在测试时，禁用此选项后推送才会显示）
4. 向下滚动到**来自应用和其他发送者的通知**
5. 确保您的浏览器已**打开**。
1. 导航至**系统设置 > 通知**
2. 确保在通知中心中已启用**通知**。
您可能需要选择**在镜像或共享显示器时允许通知**。
3. 向下滚动至应用通知列表，确保您的浏览器已打开。
某些浏览器（如 Chrome 和 Edge）会显示 2 个不同的应用条目。
1. 标准网页推送通知
2. 内部提醒（例如 Google 日历）
请确保两者都已启用。
4. 选择应用并打开设置。选择您希望如何显示通知。
某些旧版本的 Safari 可能会在应用通知列表中显示网站。在这种情况下，请确保检查网站是否已打开。
5. 导航至**系统设置 > 专注模式**，确保测试时没有启用专注模式。
1. 导航至**设置 > 通知 > 您选择的浏览器**。
2. 确保已勾选\*\*"显示通知"\*\*和您的网站。
Android 使用按应用的通知渠道。如果浏览器的通知渠道设置为静音或关闭，即使顶级开关已打开，推送通知也不会显示。在设置中，点按浏览器条目并检查每个通知渠道是否已启用并设置为可见提醒样式。
iOS 要求您先将网站添加到主屏幕，订阅者才能在 iPhone 和 iPad 上接收推送通知。在排除故障之前，请先完成 [iOS Web 推送设置](/docs/cn/web-push-for-ios)。
1. 点击浏览器的**分享**按钮，选择**添加到主屏幕**。
2. 从主屏幕打开您的网站，并在权限提示出现时允许通知。
3. 前往设备的**设置 > 通知 > 您的网站**，确保**允许通知**已开启。
### 提示显示问题
以下是网页推送通知提示可能无法按预期显示的常见原因。
检查您的[网页权限提示](/docs/cn/permission-requests)设置,以确保您已配置提示并了解不同的浏览器行为。
例如,某些浏览器(如 Safari)需要用户操作(点击按钮)才能显示原生提示。有关每个浏览器的详细信息,请参阅我们的[网页权限提示 > 原生权限提示](/docs/cn/permission-requests#native-permission-prompt)部分。
浏览器不允许用户在这些模式下订阅通知。这就是为什么滑动提示可能会显示,但原生权限提示不会显示的原因。
确保您正在[使用支持网页推送的浏览器和设备](/docs/cn/troubleshooting-web-push#browser-compatibility)。
导航至浏览器的设置并检查"通知"权限设置。Chrome 示例:`chrome://settings/content/notifications`
在此示例中:
* 用户已选择"不允许站点发送通知",这将阻止原生权限提示显示。必须显示"站点可以请求发送通知"才能允许原生权限提示显示。
* 用户已将 `https://yoursite.com` 添加到"不允许发送通知"列表中,这将阻止原生权限提示显示。必须从列表中删除此项才能允许原生权限提示显示。
**特定浏览器文档:**
* [Chrome](https://support.google.com/chrome/answer/3220216) - 此页面说明如何通过转到设置 > 隐私和安全性 > 网站设置 > 通知来管理 Chrome 中的通知,您可以在其中控制默认行为并管理各个网站的权限。
* [Firefox](https://support.mozilla.org/en-US/kb/push-notifications-firefox) - 本指南涵盖 Firefox 的网页推送通知,说明如何通过设置 > 隐私和安全性 > 通知管理通知权限,以及如何通过地址栏的站点信息图标控制特定站点的权限。
* [Safari](https://support.apple.com/guide/safari/customize-website-notifications-sfri40734/mac) - 此 Apple 指南说明如何通过 Safari > 偏好设置 > 网站 > 通知在 Mac 上自定义 Safari 通知,您可以在其中管理哪些站点可以发送通知并通过系统偏好设置控制通知行为。
* [Edge](https://support.microsoft.com/en-us/microsoft-edge/manage-website-notifications-in-microsoft-edge-0c555609-5bf2-479d-a59d-fb30a0b80b2b) - 本文详细说明如何通过导航到设置 > 隐私、搜索和服务 > 站点权限 > 通知来管理 Edge 通知,或者通过点击地址栏中的站点信息图标。
对于 iOS,需要满足一些额外要求才能提示用户订阅。更多信息请参阅 [iOS/iPadOS 移动网页推送](/docs/cn/web-push-for-ios)指南。
***
## 故障排除步骤
检查上述内容后，请按照以下步骤排除 OneSignal Web SDK 设置的故障。
浏览器的开发者工具可用于在您的网页上与我们的 Web SDK 交互，并启用日志记录以检查错误。
* **Chrome**：右键单击页面，单击*检查*，然后单击弹出窗口的*控制台*选项卡。
* **Firefox**：右键单击页面，单击*检查元素*，然后单击弹出窗口的*控制台*选项卡。
* **Safari**：转到 **Safari → 偏好设置 → 高级**，确保选中*在菜单栏中显示"开发"菜单*。然后在您的网页上右键单击，单击*检查元素*，然后单击弹出窗口的*控制台*选项卡。
* **Android 上的 Chrome**：[启用 USB 调试](https://developer.chrome.com/docs/devtools/remote-debugging/)，将设备连接到计算机，并在桌面 Chrome 浏览器中使用 `chrome://inspect#devices` 访问开发者工具。
* **Android 上的 Firefox**：[启用 USB 调试](https://developer.mozilla.org/en-US/docs/Tools/about:debugging)，将设备连接到计算机，并在桌面 Firefox 浏览器中使用 `about:debugging` 访问开发者工具。
1. [在 iOS 上启用 Web 检查器](https://developer.apple.com/library/archive/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/GettingStarted/GettingStarted.html)。
2. 在 Mac 上打开 Safari 浏览器并选择**开发 > 您的设备 > 您的站点**。
现在您可以在开发者工具控制台中运行命令。执行以下代码：
```javascript JavaScript theme={null}
OneSignal.Debug.setLogLevel('trace');
```
* 您应该看到 `undefined` 作为结果。
* 关闭选项卡并打开同一页面的新选项卡。仅刷新不会触发所有 SDK 初始化事件。
* 您将开始在控制台中看到 OneSignal SDK 日志。
### 配置错误
OneSignal 初始化后，您可能会遇到以下错误：
Error: SDK already initialized
**这意味着什么：** OneSignal Web SDK 的 `init` 代码被调用了多次，通常是由于将 WordPress 插件设置与手动代码结合使用，或意外多次添加 OneSignal `init` 代码造成的。
**如何修复：** 删除任何重复的 `init` 调用。如果使用 WordPress 插件，请从主题文件中删除任何手动 OneSignal 代码。
Error: Can only be used on: (OneSignal 控制面板中设置的 URL)
**这意味着什么：** 您当前访问的域名与 OneSignal 控制面板中配置的站点 URL 不匹配。
**如何修复：** 复制浏览器中的站点 URL 并将其粘贴到 OneSignal 控制面板的**设置 > Push & In-app > Web > 站点 URL** 配置中。确保它是使用以下格式的站点源：
* **协议：** 必须是 `https://`（对于本地测试，请参阅[Localhost 配置](./web-sdk-setup#local-testing)）
* **域名：** `example.com` 与 `www.example.com`
* **子域名：** `app.example.com` 与 `example.com`
这三个组件必须在您的实际站点 URL 和控制面板配置之间匹配。
Error: OneSignalSDK: The "My site is not fully HTTPS" option is no longer supported starting with version 16 (User Model) of the OneSignal SDK.
**这意味着什么：** 您的 OneSignal 控制面板配置为使用 HTTP 站点，而您可能已更新为使用 HTTPS。
您的用户在使用 HTTP 或"我的站点不完全是 HTTPS"选项时订阅您的站点，实际上订阅的是我们以 `https://your-label.os.tc` 格式提供给您的子域名，而不是您的实际站点源。这是因为 HTTP 站点或无法托管 service worker 的网站不支持 web push。
**如何修复：** 您有 2 个选择，但两者都需要您的用户重新订阅，因为他们实际上订阅的是 `os.tc` 子域名。
1. 创建一个新的 OneSignal 应用程序，并在 OneSignal init 代码中设置新的应用程序 ID。这样做的好处是您可以继续从旧的/原始 OneSignal 应用程序发送推送。发送尽可能多的通知，让您的用户知道站点已更新，他们应该回来再次订阅以继续获取更新。提供折扣或激励以重新订阅会有很大帮助。将"启动 URL"设置为登录页面，并为他们提供一个按钮以便轻松重新订阅，例如我们的铃铛提示、自定义链接提示或类别滑动提示。有关更多详细信息，请参阅[权限提示](./permission-requests)。
2. 如果您想保留相同的应用程序 ID，您需要使用我们的[更新应用程序](/reference/update-an-app) API 将 `chrome_web_origin` 和 `safari_site_origin` 更新为您的 HTTPS 站点源。由于这些用户订阅的是 `os.tc` 子域名,他们在浏览器中没有为您的站点允许推送权限。浏览器不"知道"他们已订阅您的站点，因此他们将再次收到提示。如果他们再次订阅，他们将在同一浏览器上拥有 2 个到您站点的 web push 订阅，并将收到重复的通知。因此，我们建议[删除所有当前的 web push 订阅者](./delete-users)以防止他们收到重复的通知。在删除之前，发送几条通知，让他们知道站点已更新，他们应该再次订阅以继续获取更新。提供折扣或激励以重新订阅效果非常好。将"启动 URL"设置为登录页面,并为他们提供一个按钮以便轻松重新订阅，例如我们的铃铛提示、自定义链接提示或类别滑动提示。有关更多详细信息，请参阅[权限提示](./permission-requests)。
### Service worker 安装错误
如果您看到[原生权限提示](./permission-requests)并单击"允许"，您可能会遇到以下 service worker 安装错误：
Y: Service Worker 注册失败。
\[Service Worker 安装] 安装 service worker 失败 TypeError：无法为范围（'`https://your-site.com/`'）使用脚本（'`https://your-site.com/...`'）注册 ServiceWorker：获取脚本时收到错误的 HTTP 响应代码（404）。
\[Service Worker 安装] 安装 service worker 失败 TypeError：无法为范围（'`https://www.yoursite.com/`'）使用脚本（'`https://www.yoursite.com/...`'）注册 ServiceWorker：获取脚本时收到错误的 HTTP 响应代码（403）。
脚本具有不受支持的 MIME 类型（'当前 MIME 类型'）。
\[Service Worker 安装] 安装 service worker 失败 SecurityError：无法为范围（'[https://your-site.com/'）使用脚本（'https://your-site.com/...'）注册](https://your-site.com/'）使用脚本（'https://your-site.com/...'）注册) ServiceWorker：脚本具有不受支持的 MIME 类型（'当前 MIME 类型'）。
\[Service Worker 安装] 安装 service worker 失败 SecurityError：无法为范围（'[https://your-site.com/'）使用脚本（'https://your-site.com/...'）注册](https://your-site.com/'）使用脚本（'https://your-site.com/...'）注册) ServiceWorker：脚本资源位于重定向之后，这是不允许的。
**这意味着什么：** 您的 service worker 文件配置不正确。
**如何修复：**
除非您指定自定义文件名或位置（如 [Service Worker 设置指南](./onesignal-service-worker)中所述），否则我们的 SDK 会在站点的根目录中查找 `OneSignalSDKWorker.js` service worker 文件。
确保您已配置正确的文件名、位置和范围，以便我们的 SDK 找到 service worker 文件。
根据您的配置，直接在浏览器中打开该文件。
* 如果您没有配置自定义位置，那么您应该在站点的根目录中看到 service worker 文件的 JavaScript 代码：`https://yoursite.com/OneSignalSDKWorker.js`
* 如果使用 WordPress，您应该在这里看到它：`https://yoursite.com/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js`
* 如果使用自定义位置，您应该在这里看到它：`https://yoursite.com/your-custom-location/OneSignalSDKWorker.js`
文件名区分大小写。确保使用 `OneSignalSDKWorker.js` 或您配置的文件名。
某些服务器会自动将文件名转换为小写。如果找不到文件，请考虑这一点。
* 您应该看到以下 JavaScript 代码：
```javascript JavaScript theme={null}
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
```
* 此文件必须以 `application/javascript` 的 `content-type` 提供。
* 此文件不能有重定向。文件必须托管在与您的站点相同的域上（不能使用 CDN 或代理域）
查看 [Service Worker 设置指南](./onesignal-service-worker)以获取更详细的设置说明。
### 通知未显示
本节假设：
1. 您已查看[通知未显示：Web Push](./notifications-not-shown-web-push)指南，了解通知可能无法在您的设备上显示的常见原因。
2. 您看到了[原生权限提示](./permission-requests)并单击了"允许"。如果您没有通过原生权限提示订阅，请参阅上面的[提示显示问题](#提示显示问题)。
如果上述条件为真，请按照以下步骤检查您的订阅 ID 并向自己发送推送通知：
在浏览器开发者工具控制台中运行以下代码：
```javascript JavaScript theme={null}
function getUserInfo() {
console.log('getUserInfo()');
Promise.all([
OneSignal.Notifications.isPushSupported(),
OneSignal.Notifications.permission,
OneSignal.User.PushSubscription.optedIn,
OneSignal.User.PushSubscription.id
]).then(([
isPushSupported,
isSubscribed,
isOptedIn,
subscriptionId
]) => {
console.log('The current URL of this page: ', location.href);
console.log('Push is supported on this browser: ', isPushSupported);
console.log('You are subscribed to notifications in the browser: ', isSubscribed);
console.log('You are opted-in with OneSignal: ' , isOptedIn);
console.log('Your OneSignal Subscription ID: ', subscriptionId);
}).catch(e => {
console.error('Error getting user info:', e);
});
}
getUserInfo();
```
这将告诉您：
* 如果有任何混淆，您所在页面的 URL。
* 您当前使用的浏览器是否支持推送通知。
* `true` 表示浏览器支持推送通知。
* `false` 表示浏览器不支持推送通知。
* 您是否在浏览器中订阅了通知。
* `true` 表示您允许了此 URL 的推送权限。
* `false` 表示您没有允许或拒绝了此 URL 的推送权限。
* 您是否已在 OneSignal 中选择加入。
* `true` 表示您的订阅已在 OneSignal 中订阅推送通知。
* `false` 表示您的订阅未在 OneSignal 中订阅推送通知。检查您的站点上是否正在调用 [`optOut()` 方法](./web-sdk-reference)。
* 您的 OneSignal 订阅 ID。
* 保存此 ID 以备下一步使用。这是您将用于向自己发送推送通知的 ID。
如果需要进一步帮助，请将此控制台数据保存到文本文件中并与我们的支持团队分享。
如果您已订阅通知、已在 OneSignal 中选择加入并拥有订阅 ID，则可以向自己发送通知。
按照[查找和设置测试订阅](./test-users)中的步骤将自己设置为测试者并向自己发送通知。
如果您没有在 Chrome 中收到通知，请使用这些 Chrome 特定的诊断工具来识别问题。
1. 在新标签页中，打开 `chrome://gcm-internals`。
2. 单击左上角的"Start Recording"按钮。确保您看到"Connection State: CONNECTED"。
3. 保持此页面打开状态，并向您的 Chrome web push 订阅发送另一个推送通知。
4. 如果您收到了通知，您应该在"Receive Message Log"中看到一些内容。
* 如果您没有看到"Data msg received"，则说明您的 Chrome 浏览器根本没有收到通知。请在支持渠道告知我们这一情况。
* 如果您看到"Data msg received"但仍未收到通知，请继续下一步。
5. 在新标签页中打开 `chrome://serviceworker-internals`
6. 搜索 `Scope: https://your-site.com`（将 `your-site.com` 替换为您的实际站点域名）。
7. 单击 **Inspect** 或 **Start -> Inspect**。将出现 Chrome 开发者工具弹出窗口。
8. 在我们的 service worker 的 Chrome 开发者工具弹出窗口上，单击 **Console** 选项卡，然后运行 `OneSignalWorker.log.trace();`。它应该返回 `undefined`。我们的 service worker 发出的任何消息现在都应该出现在此弹出窗口中。
需要帮助？
与我们的支持团队聊天或发送邮件至 `support@onesignal.com`
请包含以下信息：
* 您遇到的问题详情以及复现步骤（如有）
* 您的 OneSignal 应用 ID
* 外部 ID 或订阅 ID（如适用）
* 您在 OneSignal 控制台中测试的消息 URL（如适用）
* 任何相关的[日志或错误信息](/docs/cn/capturing-a-debug-log)
我们很乐意为您提供帮助！
***