WordPress 故障排除

常见设置问题

验证您的 OneSignal 仪表板设置

确保您已完成 WordPress 设置指南中的每个步骤：

在创建 OneSignal 应用时选择 WordPress 插件选项
您的站点 URL 必须与浏览器 URL 完全匹配
- 例如，https://example.com 与 https://www.example.com 不相同。请始终使用一个版本。
- 推送仅支持一个站点源。请参阅同源策略。
确保您至少添加了一个权限提示。

不要手动添加 OneSignal 代码

OneSignal WordPress 插件自动包含初始化脚本和 Service Worker。版本 3+ 会在插件的 sdk_files 目录中托管一个纯 OneSignalSDKWorker.js 文件，并在插件的 init 中设置该路径。您无需将 worker 上传到站点根目录，也无需自行设置 serviceWorkerPath。

请不要在您的网站中添加 OneSignal JavaScript init 代码。
请不要将自定义代码设置与插件一起使用。

如果您需要自定义代码的 init 选项或自定义 worker 位置，请卸载插件并按照自定义代码设置操作。这是从 WordPress 完全迁移，而不是重新定位插件 Service Worker 的方法。

发布文章时发送通知

当您发布文章、页面或自定义文章类型时，OneSignal 可以自动向您的订阅者发送通知。

OneSignal Push Notifications 元框——如需调整位置可拖动

如果您看不到发布或更新文章时发送通知复选框，请检查以下内容：

检查编辑器右侧和底部的元框，可按需拖放。
检查编辑器顶部的屏幕选项，确保已勾选 OneSignal Push Notifications 元框。

屏幕选项显示已勾选 OneSignal Push Notifications 元框

检查是否使用了自定义文章类型。通常可在 URL 中找到，格式为 post_type=your_custom_type。如果是，请将自定义文章类型添加到 OneSignal WordPress 插件设置中的自定义文章类型字段。

OneSignal WordPress 插件设置中显示自定义文章类型字段 — 查找自定义文章类型名称的示例位置

如何排查您的网站问题

验证插件已激活并打开开发者工具

在启用插件的正常（非隐身）浏览器窗口中加载您的网站。

浏览器开发者工具在 WordPress 站点上打开并选中控制台标签 — 右键单击您的网站，点击检查，然后打开控制台标签。

检查控制台中的 OneSignal 错误

打开控制台标签，刷新页面，并查找任何与 OneSignal 相关的红色或黄色错误。有关帮助，请参阅常见的 OneSignal 控制台错误。

在浏览器中检查订阅状态

页面加载完成且控制台中没有 OneSignal 错误后，粘贴以下内容：

JavaScript

OneSignal.User.PushSubscription.id

如果访问者已订阅，这将返回一个字符串（订阅 ID）。如果未订阅或订阅尚未就绪，您可能会看到 null 或空值。如果您看到 OneSignal is not defined，请等待几秒后再试，或先修复常见的 OneSignal 控制台错误中的控制台错误——SDK 可能仍在通过延迟加载器加载。

浏览器控制台显示 OneSignal 用户 PushSubscription id 字符串结果 — 在控制台中查找您的 OneSignal 订阅 ID。

在 OneSignal 仪表板中验证订阅 ID

在 OneSignal 仪表板中，转到 Audience > Subscriptions 并搜索上面返回的 ID。

OneSignal 仪表板订阅搜索字段显示订阅 ID 查询 — 在您的 OneSignal 仪表板中搜索订阅 ID。

发送测试推送通知

如果订阅存在且状态为已订阅，请按照推送指南发送通知。如果什么都没有显示，请参阅通知未显示获取特定于浏览器的修复方法。

常见的 OneSignal 控制台错误

SdkInitError: OneSignal: 此网页推送配置只能在…上使用。您当前的源是…

控制台 SdkInitError 显示网页推送配置源不匹配 — 站点 URL 不匹配错误。

您在 OneSignal 仪表板中的站点 URL 与您的实际域名不匹配。确保它与您在浏览器中看到的域名完全匹配。

PushPermissionNotGrantedError: 用户关闭了权限提示。

访问者拒绝了浏览器提示。在冷却期过期之前，它不会再次出现。请参阅网页权限提示了解浏览器规则，或清除站点数据以立即重试。

OneSignal Web SDK 只能初始化一次。

您加载了两次 OneSignal。如果您使用插件，请移除手动添加的 OneSignal 代码。

安装 Service Worker 失败.. 403 或 404 错误

插件从其 sdk_files 目录提供 OneSignalSDKWorker.js。从 WordPress.org 安装时使用文件夹 onesignal-free-web-push-notifications。如果您是通过 zip 安装的，文件夹名称可能不同。请替换 your-site.com 和文件夹名称，使其与 wp-admin 中的插件页面一致： https://your-site.com/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js 您应该看到这一行 JavaScript 代码：

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

如果该 URL 返回 404 或被阻止，请参阅常见插件支持修复 CDN、缓存或安全插件规则。较旧的插件版本（v2）从同一 sdk_files 目录提供 OneSignalSDKWorker.js.php。如果您的控制台仍在请求 .js.php URL，则说明您使用的是旧版 worker。请参阅 Solid Security 和 .htaccess 示例了解仅适用于这些安装的 PHP 执行注意事项。

常见插件支持

CDN 和缓存插件可能会阻止 OneSignal 所需的文件。从 WordPress.org 安装时使用插件目录 onesignal-free-web-push-notifications。如果您是通过 zip 安装的，文件夹可能不同（例如 OneSignal-WordPress-Plugin）。请检查 wp-admin 中的插件页面或 wp-content/plugins/，并在以下路径中替换该名称。使用以下特定于插件的设置：

Autoptimize

在排除脚本中添加：

wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/(.*)

WP Rocket

在 CDN > 从 CDN 中排除文件下添加：

(.*)/onesignal-free-web-push-notifications/sdk_files/(.*)

LiteSpeed Cache

在 CDN > 排除路径下添加：

(.*)/onesignal-free-web-push-notifications/sdk_files/(.*)

然后按保存。

WP Super Cache

转到 设置 > WP Super Cache > CDN
在如果包含子字符串则排除中，包含：onesignal-free-web-push-notifications
点击内容 > 删除缓存

WP Engine

WP Engine 可能通过其 CDN 重写插件 URL。HTML 后处理规则是特定于环境的；以下代码段仅为示例——在应用之前请通过 WP Engine 支持或您的用户门户确认路径。在 WP Engine 插件 > 常规设置 > HTML 后处理中，您可能需要类似以下的规则。将每个占位符替换为您的站点和 WP Engine CDN 主机名中的实际值：

占位符	替换为
`YOURSITEHERE`	您的裸域名（正则表达式片段），例如 `example.com` 对应 `example`
`mywpenginehandleHere`	您的 WP Engine 安装名称（`.wpengine.com` 前的子域名）
`wpengineCDNpathHere`	WP Engine 提供的 NetDNA / CDN 路径片段（通常显示在 CDN URL 中）
`mywebsiteHere`	您的线上站点源，不含路径，例如 `https://example.com`

#https?://(www\.)?(YOURSITEHERE\.com|mywpenginehandleHere.wpengine.com|wpengineCDNpathHere.wpengine.netdna-(ssl|cdn).com)/wp-(content|includes)#
=> https://wpengineCDNpathHere-wpengine.netdna-ssl.com/wp-$4
#https://wpengineCDNpathHere-wpengine.netdna-ssl.com/plugins/onesignal-free-web-push-notifications/#
=> https://mywebsiteHere.com/wp-content/plugins/onesignal-free-web-push-notifications/
#https://wpengineCDNpathHere-wpengine.netdna-ssl.com/wp-content/plugins/onesignal-free-web-push-notifications/#
=> https://mywebsiteHere.com/wp-content/plugins/onesignal-free-web-push-notifications/

W3 Total Cache

转到性能 > CDN
在被拒绝的文件下添加：

{plugins_dir}/onesignal-free-web-push-notifications/sdk_files/*

W3 Total Cache CDN 已拒绝文件列表，包含 OneSignal sdk_files 路径 — W3 Total Cache 排除设置。

BunnyCDN

在插件的 CDN 排除路径中排除 onesignal。

CDN Enabler

在设置 > CDN Enabler 中，在”排除”中添加：

onesignal-free-web-push-notifications

PressCDN

在排除目录中添加：

/wp-content/plugins/onesignal-free-web-push-notifications/

Breeze

在设置 > CDN > 排除内容中添加：

/onesignal-free-web-push-notifications/sdk_files/

Breeze CDN 排除内容字段包含 OneSignal sdk_files 路径 — Breeze 排除示例。

Hummingbird Pro

转到 Hummingbird > Asset Optimization。在 JavaScript（以及 CSS，如果 OneSignal 资产出现在其中）下，找到 URL 中包含 onesignal-free-web-push-notifications 或 OneSignalSDK 的文件。将其从压缩/合并/延迟中排除，或将这些资产的优化方式切换为不加载，以防止插件重写或延迟它们。

Sucuri

按照 Sucuri 的白名单指南允许 OneSignal 文件。

Solid Security（原 iThemes Security）

版本 3+ 提供静态 OneSignalSDKWorker.js 文件。该 worker 不需要在插件目录中执行 PHP。如果您仍在运行插件 v2，或者 worker URL 以 .js.php 结尾，请在系统调整下禁用在插件中禁用 PHP（或同等选项），以便 OneSignalSDKWorker.js.php 可以正常运行。

安全插件设置，显示允许插件中的 PHP 未勾选或已禁用 — 仅当您仍在使用 v2 的 .js.php worker 时，才禁用阻止插件中 PHP 执行的设置。

Defender Security plugin

版本 3+ 的 worker 不需要 PHP 执行。如果启用了阻止 PHP 执行，对于 v3 的 .js 文件来说没有问题。如果您仍在提供 OneSignalSDKWorker.js.php（v2），请保持阻止 PHP 执行处于禁用状态。转到 Defender > 安全调整并验证该设置。

Service Worker 访问的 .htaccess 示例

允许 v3 JavaScript worker。如果您的主机或安全插件阻止了 wp-content/plugins/ 中的文件，请使用此配置。

<Files OneSignalSDKWorker.js>
Require all granted
ForceType "application/javascript; charset=UTF-8"
</Files>

较旧的插件版本（v2）从同一 sdk_files 目录提供 OneSignalSDKWorker.js.php。仅当仍在使用该 .js.php URL 时才添加此代码块：

<Files *.php>
Require all denied
</Files>
<Files OneSignalSDKWorker.js.php>
Require all granted
ForceType "application/javascript; charset=UTF-8"
</Files>

Apache 2.2 使用 Order allow,deny 搭配 Allow from all / Deny from all 代替 Require。请向您的主机咨询或采用服务器已使用的语法。

发送通知后服务器速度放缓或网站无法访问

如果您的服务器在发送通知后遇到速度放缓或变得无法访问，这通常是由于通知资产的负载增加或服务器资源有限。

不要自行托管通知图标

避免自行托管通知中使用的图像。当您托管自己的通知图标或图像时，您的服务器可能会过载，因为每个接收者的浏览器都会在发送通知的同时尝试获取图像。为了减少服务器压力，请使用为高并发访问优化的图像托管解决方案或 CDN 服务。

考虑升级托管资源

如果服务器问题持续存在，您可能需要：

**升级您的托管计划：**更高的带宽或更强大的托管可能是处理大规模通知发送所必需的。
**咨询您的托管提供商：**您的提供商可以提供针对您的托管环境的见解或优化。

开始使用和设置

消息渠道

旅程

受众和自定义事件

分析和集成

隐私和安全

WordPress 故障排除

常见设置问题

验证您的 OneSignal 仪表板设置

不要手动添加 OneSignal 代码

发布文章时发送通知

如何排查您的网站问题

常见的 OneSignal 控制台错误

SdkInitError: OneSignal: 此网页推送配置只能在…上使用。您当前的源是…

PushPermissionNotGrantedError: 用户关闭了权限提示。

OneSignal Web SDK 只能初始化一次。

安装 Service Worker 失败.. 403 或 404 错误

常见插件支持

Autoptimize

WP Rocket

LiteSpeed Cache

WP Super Cache

WP Engine

W3 Total Cache

BunnyCDN

CDN Enabler

PressCDN

Breeze

Hummingbird Pro

Sucuri

Solid Security（原 iThemes Security）

Defender Security plugin

Service Worker 访问的 .htaccess 示例

发送通知后服务器速度放缓或网站无法访问

不要自行托管通知图标

考虑升级托管资源

​常见设置问题

​验证您的 OneSignal 仪表板设置

​不要手动添加 OneSignal 代码

​发布文章时发送通知

​如何排查您的网站问题

​常见的 OneSignal 控制台错误

​SdkInitError: OneSignal: 此网页推送配置只能在…上使用。您当前的源是…

​PushPermissionNotGrantedError: 用户关闭了权限提示。

​OneSignal Web SDK 只能初始化一次。

​安装 Service Worker 失败.. 403 或 404 错误

​常见插件支持

​Autoptimize

​WP Rocket

​LiteSpeed Cache

​WP Super Cache

​WP Engine

​W3 Total Cache

​BunnyCDN

​CDN Enabler

​PressCDN

​Breeze

​Hummingbird Pro

​Sucuri

​Solid Security（原 iThemes Security）

​Defender Security plugin

​Service Worker 访问的 .htaccess 示例

​发送通知后服务器速度放缓或网站无法访问

​不要自行托管通知图标

​考虑升级托管资源

常见设置问题

验证您的 OneSignal 仪表板设置

不要手动添加 OneSignal 代码

发布文章时发送通知

如何排查您的网站问题

常见的 OneSignal 控制台错误

SdkInitError: OneSignal: 此网页推送配置只能在…上使用。您当前的源是…

PushPermissionNotGrantedError: 用户关闭了权限提示。

OneSignal Web SDK 只能初始化一次。

安装 Service Worker 失败.. 403 或 404 错误

常见插件支持

Autoptimize

WP Rocket

LiteSpeed Cache

WP Super Cache

WP Engine

W3 Total Cache

BunnyCDN

CDN Enabler

PressCDN

Breeze

Hummingbird Pro

Sucuri

Solid Security（原 iThemes Security）

Defender Security plugin

Service Worker 访问的 .htaccess 示例

发送通知后服务器速度放缓或网站无法访问

不要自行托管通知图标

考虑升级托管资源