如果您无法将您的 WooCommerce 店铺连接到 Omnisend，看到“Omnisend 无法连接”错误，或者陷入授权循环，本指南将帮助您诊断并解决此问题。
大多数连接问题源于插件冲突、防火墙/安全设置、API 访问限制或不正确的店铺设置。请遵循以下诊断步骤，以识别并解决问题。
故障排除前：请确保您已遵循主要的 WooCommerce 设置指南 并完成了安装步骤。
开始之前
确保这些先决条件已满足。如果缺少任何一项，连接都将失败，无论采取何种故障排除步骤。
连接所需：
✅ WooCommerce 3.6+ 和 WordPress 5.0+早期版本不支持 REST API v3 (Omnisend 需要)。前往 Plugins → Installed Plugins 检查版本。
✅ 启用 HTTPS (SSL 证书)您的店铺 URL 必须以
https://开头。Omnisend 无法访问没有有效 SSL 证书的店铺。✅ WordPress 安装在域名根目录.WordPress 必须位于
yourdomain.com或subdomain.yourdomain.com，而不是yourdomain.com/店铺。如果 WordPress 位于页面级路径，插件会失败。✅ 已启用 REST API 访问。在您的浏览器中打开
yourdomain.com/wp-json/wc/v3/products。如果您看到产品数据或错误消息，则 API 工作正常。如果您看到 404 错误，REST API 被阻止 – 请参阅 REST API 被阻止部分.⚠️ 空的店铺槽位 (如果您已连接其他平台).如果您已将 Shopify、BigCommerce 或其他店铺连接到 Omnisend，您必须创建一个 新店铺槽位 然后才能连接 WooCommerce。每个平台都需要自己的店铺以防止数据混淆。
连接诊断清单
请按顺序完成这些步骤。完成每个步骤后，请尝试重新连接。如果连接成功，您就找到了问题。
步骤 1.验证先决条件
确认所有来自 开始之前 的要求均已满足：
WooCommerce 3.6+ 已安装
HTTPS 已启用 (URL 以
https://开头)WordPress 在域名根目录 (不是
/店铺子目录)REST API 可访问 (在
yourdomain.com/wp-json/wc/v3/products测试)已创建空店铺槽位（如果您已连接其他平台）
步骤 2.禁用已知有问题插件
这些插件经常阻止 Omnisend 连接。逐个暂时禁用它们，然后每次禁用后重试连接：
禁用插件，前往WordPress 管理后台 → 插件 → 已安装插件 → 点击停用。
WP Crontrol – 干扰 Omnisend cron jobs
LiteSpeed Cache – 剥离授权标头
真正简单的安全性 – 阻止 REST API 请求
Wordfence / Cloudflare – Firewall 拦截 Omnisend IPs
Perfmatters – 可能会禁用 REST API 或脚本
💡 连接成功后：逐一重新启用插件以找出问题所在。
步骤 3.将 Omnisend IP 地址加入白名单
如果您使用 Wordfence、Cloudflare、Really Simple Security 或任何防火墙插件，它们可能会阻止 Omnisend 请求。
跳转到 防火墙和安全插件修复部分 以将Omnisend IP和用户代理列入白名单。
如何设置白名单：
步骤 4.清除缓存并在无痕模式下测试
清除您的浏览器缓存（在 Chrome/Edge 上按 Ctrl+Shift+Delete，在 Safari 上按 Cmd+Shift+Delete）。
打开无痕/隐私窗口。
登录 WordPress 并再次尝试连接。
如果在无痕模式下问题仍然存在，可能是浏览器扩展程序或缓存会话导致了问题。暂时禁用扩展程序或使用其他浏览器。
步骤 5.检查连接状态
在 WordPress 中： 前往 Omnisend 插件页面。状态应显示已连接。
在 Omnisend 中： 前往店铺设置 →联系人信息 → 验证您的店铺 URL 是否与您的线上域名匹配 (不是 localhost 或 staging)。
测试 endpoint:
打开yourdomain.com/wp-json/omnisend-api/v1/connected in your browser.它应该返回正确。
特定错误场景
如果诊断清单未能解决您的问题，请在下方找到与您的症状相符的错误场景。
授权重定向循环
您所看到的：
您点击 "Approve" 在 WooCommerce 同意许可窗口中。
您在未完成设置的情况下被重定向回“连接您的账户”
连接无法完成。
发生此情况的原因：缓存插件、安全插件或 WP Crontrol 在审批过程中剥离了授权标头。
如何修复：
禁用 WP Crontrol： 前往Plugins →已安装插件 →停用 WP Crontrol。
暂时禁用缓存插件： 禁用 LiteSpeed Cache、WP Rocket 或任何缓存插件。
清除浏览器缓存并打开无痕窗口。
请重新连接。
如果循环持续存在：请联系您的主机提供商（SiteGround、Bluehost、GoDaddy），并请他们确认 Authorization header 没有在服务器层面被剥离。
💡 成功连接后： 逐一重新启用插件以识别阻碍因素。
插件显示已连接，但Omnisend显示“无法连接”
您所看到的：
Omnisend 插件在 WordPress 中显示 "已激活" 或 "已连接"。
Omnisend 仪表盘显示红色横幅：“Omnisend 无法连接到您的 WooCommerce。”
数据未在 WooCommerce 和 Omnisend 之间同步。
发生此情况的原因： Omnisend 无法访问您的 WooCommerce REST API，即使已安装插件。
如何修复：
检查 API密钥（API Key）：前往 WooCommerce → Settings → Advanced → REST API，并验证 Omnisend API密钥（API Key）是否存在，且未过期或被撤销。
测试 API 访问： 打开
yourdomain.com/wp-json/omnisend-api/v1/connected 在您的浏览器中。如果返回
true，则连接正常工作 – 请等待 10 分钟，然后刷新您的 Omnisend 仪表盘。如果返回
false或 404，则 API 被阻止 - 请参见 REST API 被阻止部分.
将 Omnisend IP 地址列入白名单： 添加 Omnisend IP 地址到 Wordfence、Cloudflare 或您的防火墙 – 请参阅防火墙和安全插件修复部分。
验证您的店铺 URL: 前往Omnisend →店铺设置 →联系人信息 并确认您的店铺 URL 与您的实际域名匹配（而非
localhost 或者 staging URL 类似staging.yourdomain.com)。
"Add Permissions" 按钮缺失
您看到的情况：安装插件后，您没有看到"Add permissions" 按钮在 Omnisend 插件页面上。
出现此问题的原因：旧的 Omnisend API密钥（API Key） 仍处于活动状态，阻止新的权限提示出现。
如何修复：
前往 WooCommerce → Settings → Advanced → REST API。
在列表中找到 Omnisend 密钥。
点击 "Revoke" 即可将其删除。
返回 Omnisend 插件页面。
“Add permissions”按钮现在应该出现。点击并批准。
空白页或“未找到”错误 连接期间
您所看到的：当您点击"Connect" 或"Approve," 您会看到:
空白页面
“请求的网址未在此服务器上找到” (404 错误)。
浏览器错误而不是批准弹窗。
发生此情况的原因：您的服务器正在剥离授权标头，或者 WooCommerce REST API 已禁用。
如何修复：
将授权标头添加到
.htaccess：
打开your.htaccess file（在您的 WordPress root folder 中，通过 FTP 或 cPanel File Manager）并添加以下行：SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
保存文件并重新连接。
检查 REST API 访问：
前往yourdomain.com/wp-json/wc/v3/products 在您的浏览器中。如果您看到产品数据，API 即可运行。
如果您看到 404 错误，请参见 REST API 被阻止.
联系您的主机：
某些主机（Bluehost、GoDaddy、WP Engine）默认阻止 REST API 端点。请他们启用/wp-json/ 访问
REST API 已阻止
您看到的情况：连接失败，并且yourdomain.com/wp-json/wc/v3/products 返回 404 错误或“REST API 已禁用。”
原因：REST API 被您的主机、安全插件或主题设置禁用。
如何修复：
检查安全插件:
在 Wordfence 中：前往 Wordfence → Firewall → Firewall Options 并确保 REST API 未被阻止。
在 Really Simple Security 中：前往 Settings → REST API 并允许 REST API 访问。
检查主题设置：某些主题（例如 Divi、Avada）包含禁用 REST API 的选项。请检查主题设置并重新启用它。
添加
.htaccess规则： 添加the Authorization header fix from联系主机提供商：请他们确认
/wp-json/ 端点未在服务器层面被阻止（常见于 Bluehost、GoDaddy 和 WP Engine）。
“店铺已连接”错误
您会看到： 一个横幅出现：
“此 Omnisend 店铺已连接。从您的账户中选择另一个店铺，然后重试。"
“无可用店铺槽位”
出现此情况的原因：您已有一个店铺 (Shopify、WooCommerce、BigCommerce 等) 已连接到 Omnisend，并且您尚未为此 WooCommerce 网站创建新的店铺槽位，或者您的 WooCommerce 域名之前已连接到另一个 Omnisend 账户 (包括测试账户)。
如何解决：
如果您已连接其他平台：
在 Omnisend 中创建新的店铺槽位：
前往账户设置 →Stores →“Add New Store”。切换到新的空店铺：
点击店铺切换器（Omnisend 仪表盘右上角 → Switch store），然后选择新店铺。返回 WordPress 并再次点击“连接您的账户”。
在弹窗中确认连接。
💡 为什么？ 每个平台 (Shopify, WooCommerce, BigCommerce) 必须连接到您的 Omnisend 账户中的单独店铺，以防止数据混淆。
如果您的域名之前已连接到另一个 Omnisend 账户：
请联系 Omnisend 支持团队：[email protected] 或通过应用内聊天以断开旧链接。
连接之前正常工作（突然停止）
你所看到的：
插件已连接数周或数月。
突然显示“无法连接”或同步停止。
没有进行任何更改 (您记得的)。
为什么会出现这种情况：
您的店铺 URL 略有更改（添加/删除了
www.）。最近的插件或 WooCommerce 更新撤销了 API 权限。
服务器更新期间，防火墙设置已更改。
SSL 证书已过期。
如何修复：
检查您的店铺 URL 是否已更改：前往Omnisend →店铺设置 →联系信息。如果 URL 与您的实际域名不匹配（检查是否存在
www.差异），更新它。验证 API密钥（API Key） 是否存在：前往WooCommerce →Settings →高级 →REST API。如果 Omnisend 密钥缺失，请前往 Omnisend 插件页面 → 点击"添加权限" →批准
检查您的 SSL 证书：测试地址：SSL Checker。如果已过期或无效，请通过您的托管服务提供商续订（许多提供免费的 Let's Encrypt 证书）。
如果这些都不奏效： 前往 Omnisend plugin page → 点击"添加权限" →批准 → 等待 10 分钟 → 刷新。
🔁 如果店铺连接成功但数据仍未更新，请参见下面的 连接后数据未同步。
插件更新横幅不会消失
您看到的内容： 您更新了Omnisend插件，但横幅仍然显示“需要更新”或“连接问题。”
为什么会发生这种情况： 与 Omnisend 同步插件权限的临时延迟。
如何修复：
转到 Omnisend插件页面 在WordPress中。
点击 添加权限（如果按钮出现）。
在 WooCommerce 同意许可窗口中点击 批准。
等待 510 分钟 以便更改传播。
清除您的浏览器缓存并刷新页面。
如果横幅在10分钟后仍然存在，请参阅 插件显示已连接，但Omnisend显示“无法连接”部分。
防火墙和安全插件修复
如果您使用 Wordfence、Cloudflare、Really Simple Security 或任何防火墙插件，您必须将 Omnisend 的 IP 地址和用户代理列入白名单。
Omnisend IP地址以列入白名单：
将这些 IP 地址添加到您的防火墙允许列表中：
34.170.162.11
34.56.62.59
34.56.108.215
34.133.59.36
34.58.66.146
35.184.130.5
35.232.14.89
Wordfence
要在Wordfence中将Omnisend IP列入白名单：
转到 WordPress 管理 Wordfence 防火墙。
点击 管理防火墙 滚动到 “允许的IP地址。”
在新行上粘贴每个 Omnisend IP 地址。
点击 保存更改。
返回WordPress并重试连接。
Cloudflare
要在Cloudflare中将Omnisend列入白名单：
登录到您的 Cloudflare 仪表盘
转到 安全 WAF（Web应用防火墙）
点击 创建规则
设置 规则名称：
允许Omnisend（或类似名称）设置 字段：
用户代理| 操作符：包含| 值：Omnisend/1.0（区分大小写）设置 操作：
跳过选择所有组件以跳过
点击 部署
要将Omnisend IP列入白名单：
转到 安全 WAF 工具
滚动到 IP访问规则
添加每个 Omnisend IP（见上面的联系人名单）并将 操作 设置为
允许点击 添加
保存后，在WordPress中重新安装Omnisend插件并重新连接。
非常简单的安全
要允许Omnisend请求：
转到 WordPress 管理 非常简单的安全 设置
点击 REST API
确保 REST API 未被禁用
转到 防火墙 IP允许列表
添加每个 Omnisend IP 地址（见上面的联系人名单）
保存并重试连接
数据在连接后未同步
如果您的店铺已连接，但联系人、订单、产品或产品类别缺失或看起来过时，请按照以下步骤操作。
您看到的内容：
在 Omnisend 中缺少联系人、订单、产品或产品类别。
在插件更新或店铺更改后，数据停止更新。
即使店铺显示已连接，产品或类别仍未出现。
为什么会发生这种情况：同步完全在Omnisend的后端通过WooCommerce REST API和webhooks运行。任何阻止Omnisend访问您商店的API的情况——或阻止webhooks访问Omnisend的情况——都会停止同步。
如何修复：
允许初始导入的时间。 连接或更新到插件版本1.20.0或更高版本后，Omnisend会进行一次性填充所有现有数据。对于大型商店，这可能需要长达24小时。
确认插件已更新至版本 1.20.0 或更高版本。 在旧版本中，插件可能仍会推送一些数据，同时 Omnisend 的后端也会同步这些数据。通过更新插件 在WordPress中的更新。
检查冲突的插件。 安全、火墙、缓存或修改 WooCommerce REST API 的插件可能会阻止同步。暂时禁用可疑插件以隔离冲突。常见的罪魁祸首：Wordfence、LiteSpeed Cache、Really Simple Security、Perfmatters、WP Crontrol。
验证Omnisend的IP是否已列入白名单。 请参阅允许列表中的 Omnisend IP 地址 在防火墙和安全插件修复部分。
检查 WooCommerce API 凭证。 前往WooCommerce 设置 → 高级 REST API 并确认 Omnisend API 密钥（API Key）存在且未被撤销或重新生成。如果缺失，请访问 Omnisend 插件页面 点击添加权限 批准。
检查临时/生产环境不匹配。 如果您的店铺在临时环境中连接，而实时店铺 URL 发生更改，Omnisend 可能试图连接到错误的环境。前往Omnisend 店铺设置 →联系人信息 并确认店铺 URL 与您的实时生产域名匹配。如果不匹配，请重新连接插件。
如果以上都无法解决问题，请通过 [email protected] 联系我们的支持团队或通过应用内聊天联系。
插件冲突与永久修复
如果禁用插件修复了您的连接，请使用这些永久修复，以便您可以保持插件处于活动状态。
WP Crontrol
问题： 管理WordPress定时任务并阻止Omnisend后台进程。
修复： 保持它禁用 在连接期间。连接后，仅在需要用于其他任务时重新启用。如果问题仍然存在，请保持禁用状态。
LiteSpeed 缓存
问题： 删除授权头，导致连接失败。
修复：
转到 WordPress 管理 LiteSpeed 缓存 排除
在 URI 排除 下，添加：
/wp-json/omnisend*保存设置并重试连接
Cloudflare（转轮/表单模块）
问题： 阻止 Omnisend 机器人请求。
修复： 将用户代理列入白名单Omnisend/1.0（区分大小写）在 Cloudflare WAF 规则中 -查看 Cloudflare 部分。
Perfmatters
问题： 可能禁用 REST API 或连接所需的 JavaScript.
修复：
转到 Perfmatters 设置 禁用
确保 REST API 未被禁用
重试连接
高级故障排除
克隆您的 WooCommerce 店铺（暂存/测试环境）
当您克隆您的 WooCommerce 店铺以创建测试或暂存环境时，这使您可以安全地测试新功能、更新和其他更改，而不会影响您的在线店铺。
Omnisend 插件的工作原理： Omnisend 插件通过自动断开临时环境与实时店铺的数据传输，确保您的生产环境和临时环境之间有明确的区分。它还要求临时环境连接到一个测试品牌。
设置临时环境的步骤
步骤 1：在您的生产店铺中进行操作。 使用您的托管服务提供商的工具、WordPress 插件（WP Staging、Duplicator）或手动 FTP/数据库复制来克隆您的店铺。这为测试或其他目的创建所需的环境。
步骤 2：在您的临时店铺中进行操作。 将临时插件连接到一个单独的测试品牌 在 Omnisend 中（不是您的生产品牌）。这确保临时环境链接到与您的实时店铺不同的品牌。插件显示品牌名称，使其更容易区分连接到哪个 Omnisend 品牌。
重要说明
⚠️ 自动断开连接： 当创建生产副本时，临时插件将自动与主店铺断开连接，防止其将数据发送回生产环境。
Omnisend 插件检测到创建了临时环境，并与您的实时店铺断开连接，以确保没有非生产数据发送到那里。为了让插件检测环境变化，您克隆的暂存环境必须将 WP_ENVIRONMENT_TYPE WordPress 变量设置为 "staging" 或 "development"。
这应该由您选择的克隆工具自动设置，或者如果您手动克隆，可以在您的 wp-config.php 文件中设置，例如：
define('WP_ENVIRONMENT_TYPE', 'staging');如何验证您的临时设置
如果您正在使用第三方工具来克隆您的商店，并且您想确保它创建的设置是正确的，您可以通过以下方式做到这一点：
转到您克隆的商店的 WordPress 管理仪表盘
导航到 工具 站点健康 信息 WordPress 常量
验证
WP_ENVIRONMENT_TYPE是否设置为"staging"或"development"
值如 "production" 或 "Undefined" 仅应出现在您的生产店铺中。如果它们出现在您的克隆商店中，这表明设置不正确，因为 Omnisend 插件将无法检测到需要断开连接。
有关如何克隆您的 WooCommerce 店铺并创建测试或暂存环境的详细步骤，请遵循以下指南：
品牌名称显示： Omnisend 插件显示品牌名称，以帮助您轻松识别它连接到哪个品牌。
永久链接结构问题
问题： 当永久链接结构重置时，一些 404 错误会得到解决。
修复：
转到 WordPress 管理 设置 永久链接。
点击 保存更改（即使没有进行更改）。
重试连接。
SSL 证书问题
问题： 一个 无效或过期的 SSL 证书阻止 API 访问.
修复：
在 SSL 检查器. 检查您的 SSL 证书。
如果过期或无效，请通过您的托管提供商续订（许多提供免费的 Let's Encrypt 证书）。
续订后，重试连接。
服务器级授权头阻止
问题： 一些主机（SiteGround、Bluehost、GoDaddy）默认会去除 Authorization 头。
修复：
将此行添加到您的
.htaccess文件中（在 WordPress 根目录）：SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
如果问题仍然存在，请联系您的托管服务提供商，并要求他们为 REST API 请求启用授权头透传。
如何修复 API 访问问题
由于API访问问题，您的店铺数据将无法同步到Omnisend。这会阻止您向您的受众发送消息。如果您的商店数据未同步，API 访问可能被以下原因阻止：
安全插件（第三方）。
自定义 PHP 代码阻止 API 访问.
WordPress 或 WooCommerce 安全设置。
请联系您的开发人员以识别和解决任何潜在原因。
检查 WooCommerce API 是否可访问：
转到 WooCommerce → 设置 → 高级 → REST API.
点击 添加密钥。
输入任何名称并点击 生成 API 密钥。
获取消费者密钥和秘密，然后在浏览器中输入此 URL：
{shopDomain}/wp-json/wc/v3/products?consumer_key={consumer_key}&consumer_secret={consumer_secret}如果产品联系人名单出现，API 就正常工作。
检查后删除测试 API 密钥。
检查 Omnisend API 是否可访问的方法：
更新到最新的 Omnisend 插件版本。
在浏览器中打开
{shopDomain}/wp-json/omnisend-api/v1/connected- 它应该返回true。
验证您的修复是否有效
在应用任何修复后，确认连接是否处于活动状态：
在 WordPress 中： 转到Omnisend 插件页面。状态应显示"已连接。"
在 Omnisend 中： 转到受众 联系人 并确认店铺联系人出现。
测试端点： 在浏览器中打开
yourdomain.com/wp-json/omnisend-api/v1/connected。它应该返回真的。
常见问题解答
插件在 WordPress 中显示“已连接”，但 Omnisend 却说“无法连接”。为什么？
这意味着 Omnisend 无法访问您的 WooCommerce API，即使插件处于活动状态。检查您的 WooCommerce REST API 是否可访问，在防火墙中将 Omnisend IP 地址列入白名单，并验证您在 Omnisend 中的店铺 URL 是否与您的实际域名匹配（而不是 localhost）。
在连接时，“请求的 URL 在此服务器上未找到”是什么意思？
此错误意味着您的服务器正在阻止或错误配置 WooCommerce REST API 端点。添加SetEnvIf Authorization "(.*)\" HTTP_AUTHORIZATION=$1 到你的.htaccess 文件，或联系您的托管服务提供商以启用 REST API 访问。
为什么点击“连接”会显示一个空白白页？
连接期间出现空白页面表示您的服务器正在剥离 Authorization 头或某个插件正在阻止 API 请求。添加the Authorization header fix to .htaccess（见上文），暂时禁用缓存/安全插件，然后重试。
我更新了插件，但横幅仍然显示“需要更新。”现在该怎么办？
更新后，前往 WordPress 中的 Omnisend 插件页面并点击"添加权限." 等待 5–10 分钟，清除您的浏览器缓存，然后刷新。如果横幅仍然存在，请参见插件显示已连接，但Omnisend显示“无法连接”部分。
WP Crontrol 正在导致问题。这个插件有什么用？
WP Crontrol 管理 WordPress 定时任务（计划任务）。它可能会干扰 Omnisend 的后台进程。暂时禁用它，完成连接，然后重新启用。如果问题仍然存在，请保持禁用或联系支持。
我需要为 Omnisend 白名单哪些 IP 地址？
在 Wordfence、Cloudflare、Really Simple Security 或任何防火墙插件中将这些 IP 列入白名单：34.170.162.11, 34.56.62.59, 34.56.108.215, 34.133.59.36, 34.58.66.146, 35.184.130.5, 35.232.14.89。
我使用 Cloudflare。如何将 Omnisend 列入白名单？
前往Cloudflare → Security → WAF → Create a rule. 将用户代理列入白名单Omnisend/1.0（区分大小写）并将Omnisend IP地址（请参见上面的常见问题解答）添加到您的允许列表中。保存后，重新安装 Omnisend 插件。
我的店铺 URL 更改了（从 localhost 或临时环境）。我该如何重新连接？
前往Omnisend → Store Settings → Contact information and update your store URL to the live domain. 等待10分钟，然后注销并重新登录。如果问题仍然存在，请从WordPress中断开并重新连接插件。
为什么我的 WooCommerce 店铺在连接到 Omnisend 后变得缓慢？
如果您使用的插件版本低于 1.20.0，插件可能仍会推送一些数据，而 Omnisend 的后端也会同步这些数据，从而在联系人、订单、产品和产品类别之间造成双重同步负载。Update to version 1.20.0 or later to resolve this.前往插件 →WordPress中的更新。
如果您有任何问题或需要帮助，请通过 [email protected] 联系我们的支持团队或通过应用内聊天联系。