如果您无法将您的 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.验证先决条件
请确认 Before You Begin 中的所有要求均已满足：
WooCommerce 3.6+ 已安装
HTTPS 已启用 (URL 以
https://开头)WordPress 在域名根目录 (不是
/店铺子目录)REST API 可访问 (在
yourdomain.com/wp-json/wc/v3/products测试)已创建空店铺槽位（如果您已连接其他平台）
步骤 2.禁用已知有问题插件
这些插件经常阻止 Omnisend 连接。逐个暂时禁用它们，然后每次禁用后重试连接：
禁用插件，前往 WordPress Admin → Plugins → Installed Plugins → 点击 Deactivate。
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 在您的浏览器中。它应该返回真。
具体错误场景
如果诊断清单未能解决您的问题，请在下方找到与您的症状相符的错误场景。
授权重定向循环
您所看到的：
您在 WooCommerce 同意许可 窗口中点击 "Approve"。
您将返回到 "Connect your account"，但未完成设置。
连接永不完成。
出现此问题的原因：缓存插件、安全插件或 WP Crontrol 在审批流程中剥离了 Authorization header。
如何修复：
禁用 WP Crontrol： 前往Plugins → Installed Plugins停用 WP Crontrol。
暂时禁用缓存插件： 停用 LiteSpeed Cache、WP Rocket 或任何缓存插件。
清除浏览器缓存并打开无痕窗口。
请再次连接。
如果循环持续存在： 联系您的主机提供商 (SiteGround、Bluehost、GoDaddy) 并请他们确认 Authorization 标头未在服务器级别被剥离。
💡 成功连接后：逐个重新启用插件以识别阻止因素。
插件显示已连接，但 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 Blocked section。
将 Omnisend IP 地址列入白名单： 添加 Omnisend IP 地址到 Wordfence、Cloudflare 或您的防火墙 – 请参阅防火墙和安全插件修复部分
验证您的店铺 URL: 前往Omnisend → 店铺设置 → 联系人信息 并确认您的店铺 URL 匹配您的实际域名（而非
localhost 或 staging URL，例如staging.yourdomain.com)。
"Add Permissions" Button" 缺失
您看到的是：安装插件后，您没有看到"Add permissions" 按钮在 Omnisend 插件页面上。
出现此情况的原因：旧的 Omnisend API密钥（API Key）仍处于活动状态，阻止了新的权限提示出现。
如何修复：
前往 WooCommerce → Settings → Advanced → REST API。
在联系人名单中找到Omnisend密钥。
点击 "Revoke" 即可删除。
返回 Omnisend 插件页面。
“Add permissions” 按钮现在应该会显示。点击它并批准。
连接期间出现空白页面或“未找到”错误
您所看到的： 当您点击"Connect" 或"Approve," 您会看到：
一张空白的白色页面。
请求的 URL 在此服务器上未找到 (404 错误)。
浏览器错误而不是批准弹窗。
出现此问题的原因：您的服务器正在剥离授权标头，或者 WooCommerce REST API 已禁用。
如何修复：
将授权标头添加到
.htaccess：
打开your.htaccess file (在您的 WordPress 根文件夹中，通过 FTP 或 cPanel 文件管理器) 并添加此行:SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
保存文件并重新连接。
检查 REST API 访问:
前往在您的浏览器中输入 yourdomain.com/wp-json/wc/v3/产品。如果您看到产品数据，API 正常工作。
如果您看到 404 错误，请参阅 REST API 被阻止。
联系您的主持人:
某些主机（Bluehost、GoDaddy、WP Engine）默认情况下会阻止 REST API 端点。请他们启用/wp-json/ 访问。
REST API 已阻止
您会看到：连接失败，并且yourdomain.com/wp-json/wc/v3/products 返回 404 error 或 "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/ endpoints 未在服务器级别被阻止（Bluehost、GoDaddy 和 WP Engine 等主机服务商常见）。
"店铺已连接" 错误
您会看到： 出现一个横幅：
此 Omnisend 店铺已连接。从您的账户中选择另一个店铺，然后重试。
没有可用的店铺名额
出现此情况的原因：您已有一个店铺 (Shopify、WooCommerce、BigCommerce 等) 连接到 Omnisend，并且您尚未为此 WooCommerce 站点创建一个新的店铺槽位，或者您的 WooCommerce 域名之前已连接到另一个 Omnisend 账户 (包括测试账户)。
如何修复：
如果您已连接其他平台：
在 Omnisend 中创建新的店铺：
前往账户设置 → 店铺 → 添加新店铺切换到新的空店铺:
点击店铺切换器 (Omnisend 仪表盘右上角 → Switch store) 并选择新的店铺。返回 WordPress 并再次点击 "连接您的账户"。
批准连接在弹窗中。
💡 为什么？ 每个平台 (Shopify, WooCommerce, BigCommerce) 必须连接到您的 Omnisend 账户中的单独店铺，以防止数据混淆。
如果您的域名之前已连接到另一个 Omnisend 账户:
请联系我们的支持团队，通过[email protected] 或应用内聊天以断开旧链接。
连接以前正常工作（突然停止）
您所看到的：
插件已连接数周或数月。
突然显示“无法连接”或者同步停止。
没有进行任何更改 (您不记得)。
为什么会发生这种情况：
您的店铺 URL 略有更改（添加/删除
www.）。最近的插件或 WooCommerce 更新撤销了 API 权限。
服务器更新期间，防火墙设置已更改。
SSL 证书已过期。
如何修复：
检查您的店铺 URL 是否更改： 前往Omnisend → 店铺设置 → 联系人信息。如果 URL 与您的实际域名不匹配（请检查
www.差异），更新它。验证 API密钥（API Key） 是否存在： 前往WooCommerce → Settings → Advanced → REST API。如果 Omnisend 密钥缺失，前往 Omnisend 插件页面 → 点击"Add permissions"批准
检查您的 SSL 证书：在此测试SSL Checker。如果过期或无效，请通过您的主机提供商续订（许多提供免费的 Let's Encrypt 证书）。
如果这些都不奏效： 前往 Omnisend 插件页面 → 点击"Add permissions"Approve → 等待 10 分钟 → 刷新。
插件更新横幅不会消失
您看到的情况：您更新了 Omnisend 插件，但横幅仍显示“Update required”或“Connection issue”。
发生此情况的原因： 与 Omnisend 同步插件权限时出现暂时性延迟。
如何修复：
前往 WordPress 中的 Omnisend 插件页面。
点击 "Add permissions" (如果按钮出现)。
在 WooCommerce 同意许可窗口中点击 批准。
等待5-10分钟，以便更改生效。
清除您的浏览器缓存并刷新页面。
如果横幅在10分钟后仍然存在，请参阅插件显示已连接，但 Omnisend 显示“Unable to Connect”部分。
防火墙和安全插件修复
如果您使用 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 Admin → Wordfence → Firewall.
点击 Manage Firewall → 滚动到 "Allowlisted IP addresses."
请将每个 Omnisend IP 地址粘贴到新行上。
点击 "Save Changes"。
返回 WordPress 并重新连接。
Cloudflare
在 Cloudflare 中将 Omnisend 加入白名单：
登录您的 Cloudflare 仪表盘
前往Security → WAF (Web Application Firewall)
点击 "Create Rule"
设置 规则名称：
Allow Omnisend（或类似）设置 字段:
User Agent| 运算符:contains| 值:Omnisend/1.0（区分大小写）设置 动作：
跳过选择所有要跳过的组件
点击 "Deploy"
将 Omnisend IP 列入白名单：
前往 Security → WAF → Tools
滚动到 IP Access Rules
添加每个 Omnisend IP (请参阅上方列表) 并将 Action 设置为
Allow点击 "Add"
保存后，在 WordPress 中重新安装 Omnisend 插件并重新连接。
真正简单的安全性
允许 Omnisend 请求：
前往 WordPress Admin → Really Simple Security → Settings
点击 REST API
确保 REST API 未禁用
前往 Firewall → IP Allowlist
添加每个 Omnisend IP 地址（请参阅上面的列表）
保存并重试连接
插件冲突与永久修复
如果禁用插件解决了您的连接问题，请使用这些永久性修复方案，以便您可以保持插件处于活动状态。
WP Crontrol
问题：管理 WordPress cron 作业并阻止 Omnisend 后台进程。
修复：保持不变连接期间禁用。连接后，仅当您需要它执行其他任务时才重新启用。如果问题仍然存在，请保持禁用状态。
LiteSpeed Cache
问题：剥离授权标头，导致连接失败。
修复：
前往 WordPress Admin → LiteSpeed Cache → Exclude
在 URI Exclude 下，添加：
/wp-json/omnisend*保存设置并重新连接
Cloudflare (Turnstile / Forms Module)
问题：拦截 Omnisend 机器人请求。
修复： Whitelist the user-agentCloudflare WAF 规则中的 Omnisend/1.0（区分大小写）–请参阅 Cloudflare 部分
Perfmatters
问题：可能会禁用连接所需的 REST API 或 JavaScript。
修复：
前往 Perfmatters → Settings → Disable
确保 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 管理仪表盘
前往 Tools → Site Health → Info → WordPress Constants
请确认
WP_ENVIRONMENT_TYPE已设置为"staging"或"development"
诸如 "production" 或 "Undefined" 之类的值应仅出现在您的生产店铺中。如果它们出现在您的克隆店铺中，这表明设置不正确，因为 Omnisend 插件将无法检测到它需要断开连接。
有关如何克隆您的 WooCommerce 店铺并创建测试或暂存环境的详细步骤，请遵循以下指南：
品牌名称显示： Omnisend 插件会显示品牌名称，以帮助您轻松识别它连接到哪个品牌。
永久链接结构问题
问题：一些 404 错误在永久链接结构重置后得到解决。
修复：
前往 WordPress Admin → Settings → Permalinks.
点击 "Save Changes" (即使未进行任何更改)。
重试连接。
SSL证书问题
问题： 无效或过期的 SSL 证书阻止 API 访问。
修复：
在 SSL 检查器 检查您的 SSL 证书。
如果已过期或无效，请通过您的托管服务提供商续订（许多提供免费的 Let's Encrypt 证书）。
续订后，请重新连接。
服务器级授权标头阻止
问题：某些主机（SiteGround、Bluehost、GoDaddy）默认情况下会移除 Authorization header。
修复：
将此行添加到您的
.htaccess文件（在 WordPress 根目录中）：SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
如果问题仍然存在，请联系您的主机提供商，并请他们启用针对 REST API 请求的授权标头直通。
如何解决 API 访问问题
由于 API 访问问题，您的店铺数据将无法同步到 Omnisend。这会阻止 Omnisend 向您的受众发送消息。如果您的店铺数据未同步，API 访问可能会被以下原因阻止：
安全插件 (第三方)
自定义 PHP 代码阻止 API 访问。
WordPress 或 WooCommerce 安全设置
请联系您的开发人员，以识别并解决任何潜在原因。
检查 WooCommerce API 是否可访问：
前往 WooCommerce → Settings → Advanced → REST API.
点击 "Add key"
输入任意名称，然后点击 生成 API密钥（API Key）。
获取 consumer key 和 secret，然后在您的浏览器中输入此 URL：
{shopDomain}/wp-json/wc/v3/products?consumer_key={consumer_key}&consumer_secret={consumer_secret}如果产品列表出现，API 正常工作。
检查后删除测试API密钥（API Key）。
检查 Omnisend API 是否可访问：
更新到最新的 Omnisend 插件版本。
在浏览器中打开
{shopDomain}/wp-json/omnisend-api/v1/connected—它应该返回true。
确认您的修复已奏效
应用任何修复后，确认连接已激活：
在 WordPress 中：前往Omnisend 插件页面。状态应显示已连接。
在 Omnisend 中： 前往受众 → Contacts 并确认店铺联系人显示。
Test Endpoint: 打开
yourdomain.com/wp-json/omnisend-api/v1/connected 在您的浏览器中。它应该返回是。
常见问题
插件在 WordPress 中显示“已连接”，但 Omnisend 显示“无法连接”。为什么？
这意味着 Omnisend 无法访问您的 WooCommerce API，即使插件已激活。确保您的 WooCommerce REST API 可访问，将 Omnisend IP 地址列入您的防火墙白名单，并验证您在 Omnisend 中的店铺 URL 与您的实际域名匹配（而非 localhost）。
在连接期间，"请求的网址在此服务器上未找到"是什么意思？
此错误意味着您的服务器正在阻止或配置错误 WooCommerce REST API 端点。添加SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 到您的.htaccess 文件，或联系您的主机提供商以启用 REST API 访问。
为什么点击 “Connect” 会显示一个空白页面？
连接时出现空白页，表明您的服务器正在剥离 Authorization header，或者某个插件正在阻止 API 请求。添加the Authorization header fix to .htaccess (见上文)，暂时禁用缓存/安全插件，然后重试。
我更新了插件，但横幅仍然显示“update required.”现在怎么办？
更新后，前往 WordPress 中的 Omnisend 插件页面并点击"Add permissions." 请等待 5-10 分钟，清除您的浏览器缓存，并刷新。如果横幅仍然存在，请参阅插件显示已连接，但 Omnisend 显示“Unable to Connect”部分。
WP Crontrol 导致了问题。这个插件是做什么用的？
WP Crontrol 管理 WordPress cron jobs (计划任务)。这可能会干扰 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. 将 user-agent 列入白名单Omnisend/1.0（区分大小写）并添加 Omnisend IP 地址（请参阅上面的常见问题解答）到您的允许列表。保存后，请重新安装 Omnisend 插件。
您的店铺 URL 更改了（从 localhost 或 staging）。您如何重新连接？
前往Omnisend → Store Settings → Contact information and update your store URL to the live domain. 等待 10 分钟，然后登出并重新登录。如果问题仍然存在，请断开连接并重新连接 WordPress 插件。
如果您有任何疑问或需要帮助，请联系我们的支持团队，通过 [email protected] 或通过应用内聊天。