> ## 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.
# WordPress 故障排除
> 在 WordPress 上排查 OneSignal Web Push 通知常见设置问题的综合指南，包括浏览器兼容性（Chrome、Firefox、Safari）、插件集成以及解决 CDN 或缓存冲突。
## 常见设置问题
### 验证您的 OneSignal 仪表板设置
确保您已完成 [WordPress 设置指南](./wordpress) 中的每个步骤：
* 在创建 OneSignal 应用时选择 **WordPress 插件** 选项
* 您的站点 URL 必须与浏览器 URL 完全匹配
* 例如，`https://example.com` 与 `https://www.example.com` **不**相同。请始终使用一个版本。
* 推送仅支持一个站点源。请参阅[同源策略](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)。
* 确保您至少添加了一个权限提示。
### 不要手动添加 OneSignal 代码
OneSignal WordPress 插件**自动**包含初始化脚本和 Service Worker。
* 请**不要**在您的网站中添加 OneSignal JavaScript `init` 代码。
* 请**不要**将[自定义代码设置](./web-push-custom-code-setup)与 WordPress 插件一起使用。如果您需要自定义 `init` 方法，请**卸载插件**并手动添加代码和 Service Worker。
### 发布文章时发送通知
当您发布文章、页面或自定义文章类型时，OneSignal 可以自动向您的订阅者发送通知。
如果您看不到**发布或更新文章时发送通知**复选框，请检查以下内容：
1. 检查编辑器右侧和底部的元框，可按需拖放。
2. 检查编辑器顶部的**屏幕选项**，确保已勾选 **OneSignal Push Notifications** 元框。
3. 检查是否使用了自定义文章类型。通常可在 URL 中找到，格式为 `post_type=your_custom_type`。如果是，请将自定义文章类型添加到 [OneSignal WordPress 插件设置](./wordpress#add-a-custom-post-type-to-onesignal-wordpress-plugin)中的**自定义文章类型**字段。
***
## 如何排查您的网站问题
在启用插件的正常（非隐身）浏览器窗口中加载您的网站。
打开**控制台**标签，刷新页面，并查找任何与 OneSignal 相关的红色或黄色错误。
有关帮助，请参阅[常见的 OneSignal 控制台错误](#common-onesignal-console-errors)。
页面加载完成且控制台中没有 OneSignal 错误后，粘贴以下内容：
```javascript JavaScript theme={null}
OneSignal.User.PushSubscription.id
```
如果访问者已订阅，这将返回一个字符串（订阅 ID）。如果未订阅或订阅尚未就绪，您可能会看到 **`null`** 或空值。如果您看到 **`OneSignal is not defined`**，请等待几秒后再试，或先修复[常见 OneSignal 控制台错误](#common-onesignal-console-errors)中的控制台错误——SDK 可能仍在通过延迟加载器加载。
在 **OneSignal 仪表板**中，转到 **Audience > Subscriptions** 并搜索上面返回的 ID。
如果订阅存在且状态为**已订阅**，请按照[推送指南](./push)发送通知。
如果什么都没有显示，请参阅[未显示通知](./notifications-not-shown-web-push)获取特定于浏览器的修复方法。
***
## 常见的 OneSignal 控制台错误
### SdkInitError: OneSignal: 此网络推送配置只能在...上使用。您当前的源是...
您在 OneSignal 仪表板中的站点 URL 与您的实际域名不匹配。
确保它与您在浏览器中看到的域名完全匹配。
### PushPermissionNotGrantedError: 用户关闭了权限提示。
访问者拒绝了浏览器提示。在冷却期过期之前，它不会再次出现。
请参阅[Web 权限提示](./permission-requests)了解浏览器规则，或清除站点数据以立即重试。
### 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`
如果不能访问，请参阅[常见插件支持](#common-plugin-support)修复 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
1. 转到 **设置 > WP Super Cache > CDN**
2. 在 **如果包含子字符串则排除** 中，包含：`onesignal-free-web-push-notifications`
3. 点击 **内容** > **删除缓存**
### WP Engine
WP Engine 可能通过其 CDN 重写插件 URL。**HTML 后处理**规则是特定于环境的；以下代码段仅为**示例**——在应用之前请通过 [WP Engine 支持](https://wpengine.com/support/)或您的用户门户确认路径。
在 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 text theme={null}
#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
1. 转到 **性能 > CDN**
2. 在 **被拒绝的文件**下添加：
```
{plugins_dir}/onesignal-free-web-push-notifications/sdk_files/*
```
### 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/
```
### Hummingbird Pro
转到 **Hummingbird > Asset Optimization**。在 **JavaScript**（以及 **CSS**，如果 OneSignal 资产出现在其中）下，找到 URL 中包含 **`onesignal-free-web-push-notifications`** 或 **`OneSignalSDK`** 的文件。将其从压缩/合并/延迟中**排除**，或将这些资产的优化方式切换为**不加载**，以防止插件重写或延迟它们。
### Sucuri
按照 [Sucuri 的白名单指南](https://kb.sucuri.net/firewall/Whitelist+and+Blacklist/whitelist-file-folder)允许 OneSignal 文件。
### Solid Security（原 iThemes Security）
在**系统调整**下禁用**在插件中禁用 PHP**（或同等选项），以便 `OneSignalSDKWorker.js.php` 可以正常运行。
### Defender Security plugin
不要启用"阻止 PHP 执行"。
转到 Defender 插件 > 安全调整并验证该设置已禁用。
### Service Worker 访问的 .htaccess 示例
```apache theme={null}
Order allow,deny
Deny from all
Allow from all
ForceType 'application/javascript; charset=UTF-8'
Allow from all
ForceType 'application/javascript; charset=UTF-8'
```
Apache 2.4+ 通常使用 `Require all denied` / `Require all granted` 代替 `Order allow,deny`。请向您的主机咨询或根据服务器的 Apache 版本调整规则。
***
## 发送通知后服务器速度放缓或网站无法访问
如果您的服务器在发送通知后遇到速度放缓或变得无法访问，这通常是由于通知资产的负载增加或服务器资源有限。
### 不要自行托管通知图标
避免自行托管通知中使用的图像。当您托管自己的通知图标或图像时，您的服务器可能会过载，因为每个接收者的浏览器都会在发送通知的同时尝试获取图像。
为了减少服务器压力，请使用为高并发访问优化的图像托管解决方案或 CDN 服务。
### 考虑升级托管资源
如果服务器问题持续存在，您可能需要：
* \*\*升级您的托管计划：\*\*更高的带宽或更强大的托管可能是处理大规模通知发送所必需的。
* \*\*咨询您的托管提供商：\*\*您的提供商可以提供针对您的托管环境的见解或优化。
***