WordPress 故障排除

常见设置问题

验证您的 OneSignal 仪表板设置

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

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

不要手动添加 OneSignal 代码

OneSignal WordPress 插件自动包含初始化脚本和 Service Worker。

请不要在您的网站中添加 OneSignal JavaScript init 代码。
请不要将自定义代码设置与 WordPress 插件一起使用。如果您需要自定义 init 方法，请卸载插件并手动添加代码和 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: 用户关闭了权限提示。

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

OneSignal 网络 SDK 只能初始化一次。

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

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

确保此文件可访问（将 your-site.com 替换为您的实际域名，并匹配您的实际插件文件夹名称，如果与默认名称不同）： https://your-site.com/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js 如果不能访问，请参阅常见插件支持修复 CDN 或缓存问题。

常见插件支持

CDN 和缓存插件可能会阻止 OneSignal 所需的文件。以下路径假设插件目录为 onesignal-free-web-push-notifications；如果您的安装使用了不同的文件夹名称，请相应调整。

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`

text

#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）

在系统调整下禁用在插件中禁用 PHP（或同等选项），以便 OneSignalSDKWorker.js.php 可以正常运行。

安全插件设置，显示允许插件中的 PHP 未勾选或已禁用 — iThemes PHP 插件设置。

Defender Security plugin

不要启用”阻止 PHP 执行”。转到 Defender 插件 > 安全调整并验证该设置已禁用。

Service Worker 访问的 .htaccess 示例

<Files *.php>
Order allow,deny
Deny from all
</Files>
<Files OneSignalSDKWorker.js.php>
Allow from all
ForceType 'application/javascript; charset=UTF-8'
</Files>
<Files OneSignalSDKWorker.js>
Allow from all
ForceType 'application/javascript; charset=UTF-8'
</Files>

Apache 2.4+ 通常使用 Require all denied / Require all granted 代替 Order allow,deny。请向您的主机咨询或根据服务器的 Apache 版本调整规则。

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

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

不要自行托管通知图标

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

考虑升级托管资源

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

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

开始使用和设置

消息渠道

旅程

受众和自定义事件

分析和集成

隐私和安全

WordPress 故障排除

常见设置问题

验证您的 OneSignal 仪表板设置

不要手动添加 OneSignal 代码

发布文章时发送通知

如何排查您的网站问题

常见的 OneSignal 控制台错误

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

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

OneSignal 网络 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 网络 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 网络 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 示例

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

不要自行托管通知图标

考虑升级托管资源