互 互客鱼 返回主站
/

WordPress 和 WooCommerce

故障排除

针对最常见的 WordPress 插件问题的症状优先指南。 每个修复都基于实际的代码路径 — 没有理想化的建议。

小部件未在网站上显示

按顺序检查：

  1. 插件已配置？ 打开 Settings → hukeyu。所有三个字段（base URL、API token、agent）必须填写。Enabled 开关必须开启。
  2. 正确的帖子类型？ "Post types" 复选框控制哪些单独页面加载小部件。默认情况下只有 post + page 被选中。WooCommerce product 页面需要显式选择加入。
  3. 主题调用 wp_footer()？ 插件通过 add_action('wp_footer', …, 99) 注入脚本。从 footer.php 中省略 wp_footer() 的主题不会加载小部件。大多数现代主题都会调用它；旧版自定义主题偶尔不会。
  4. 缓存插件提供陈旧快照？ WP Rocket、W3 Total Cache、LiteSpeed 和 Cloudflare APO 都可以将预小部件 HTML 版本缓存数天。刷新受影响 URL 的页面缓存。
  5. 浏览器阻止小部件脚本？ 打开 DevTools → Network。对 {base_url}/widget/widget.js 的请求应返回 200。如果您在控制台中看到 connect-src 违规，您的 CSP 需要允许列表条目。详见 允许的源。

"Test connection" 失败

错误消息诊断
"Connection failed." 网络级别 — 从 WP 无法访问 hukeyu 主机。运行 wp shell，尝试 wp_remote_get('https://app.hukeyu.example/up')。常见原因：出站防火墙阻止 hukeyu 主机。
HTTP 401 invalid_token Token 明文错误（粘贴时拼写错误）或 token 在 /settings/api-tokens 中被撤销。重新颁发一个新的。
HTTP 403 insufficient_ability Token 未使用 wp:integration 能力创建。用正确的范围重新颁发。
"Enter both a base URL and an API token, then try again." 其中一个表单字段为空。插件在客户端防御以避免浪费请求。
"Base URL must start with http:// or https://." SettingsValidator 拒绝没有方案的 URL。粘贴带有 https:// 的完整 base URL。
"API token format looks wrong" 插件期望 pbar_ + 48 个字母数字字符。要么粘贴了错误的字符串，要么 token 在复制时被截断。

"Sync now" 完成但互客鱼看不到新内容

同步 POST 成功返回，但互客鱼管理员的 Sources 页面没有显示帖子。可能性：

  1. 同步仍在恢复中。 在大型站点（500+ 帖子）上，第一次传递只执行 20 秒内适合的内容。其余部分在 30 秒后的 WP-Cron tick 上完成。管理员显示柔和通知："hukeyu is finishing a large-site sync in the background." 等待、刷新，计数会增加。
  2. 索引已排队，不是同步的。 互客鱼接受上传并在 Horizon 上排队 IndexDocumentJob。在繁忙的工作器上，这可能会延迟 30-60 秒。检查 /admin/system → Failed jobs 是否有任何错误。
  3. 向量存储正在配置中。 全新的 Cloudflare Vectorize 索引在查询返回结果之前需要大约 2 分钟。Upserts 立即成功；读取返回 0。创建后的第一批 upserts 也可能静默丢失 — 重新运行同步。
  4. 内容哈希匹配。 如果您之前同步了帖子且没有任何更改，响应的 skipped_unchanged 计数会增加而无需重新索引。Document 已经存在；这是按预期工作的。

同步恢复但从未完成

恢复 transient（hukeyu_post_sync_resume 或 hukeyu_product_sync_resume）位于 wp_options 中， 但 WP-Cron 延续从未触发。最可能的原因：

  • WP-Cron 已禁用。 检查 wp-config.php 中的 define('DISABLE_WP_CRON', true);。某些主机禁用它并通过真正的系统 cron 运行 cron — 与您的主机确认。如果 WP-Cron 完全禁用，从设置页面再次手动运行 "Sync now"；同步器在第一次调用时读取恢复标记并从停止的地方继续。
  • WP-Cron 静默失败。 在命令行上运行 wp cron event list。hukeyu_run_full_sync_event / hukeyu_run_product_sync_event 条目应显示过去的时间戳作为下次运行时间。wp cron event run --due-now 强制它们运行。
  • 站点从未接收流量。 WP-Cron 是机会主义的 — 它在计划时间后的下一个页面视图上运行。没有访问者的暂存站点不会触发 cron。要么访问任何前端页面，要么手动触发钩子：wp eval '(new \hukeyu\Sync\PostSyncer)->runFullSync();'。

强制清除卡住的恢复标记

如果您想从第 1 页开始下一次同步：

wp transient delete hukeyu_post_sync_resume
wp transient delete hukeyu_product_sync_resume

下一次 "Sync now" 点击然后从第 1 页重新枚举。 重新同步很便宜 — 互客鱼的 content_hash 短路避免重新嵌入未更改的帖子。

Elementor / Bricks / Oxygen 页面同步为空内容

三种可能性：

  1. 页面构建器版本更改了其渲染器签名。 插件反射到 \Elementor\Plugin::$instance->frontend->get_builder_content_for_display、FLBuilder::render_content_by_id 和 \Bricks\Frontend::render_content。重命名这些的主要版本返回空字符串，插件回退到普通路径。确认：wp eval '$post = get_post(YOUR_ID); echo (new \hukeyu\Sync\PageBuilderContent)->detectBuilder($post);'。
  2. 页面在构建器中确实是空的。 在 WP 管理员中打开帖子并在构建器中编辑 — 有时迁移会损坏 postmeta，构建器显示 "Default content" 占位符。在构建器级别修复；同步会在下次保存时获取。
  3. 您在自定义 hukeyu_post_content_html 过滤器后面。 如果您的代码从过滤器返回空字符串，则不发送任何内容。检查 functions.php / mu-plugins / 任何自定义插件。

购物车页面上的优惠券应用按钮不起作用

  1. 访客没有 hukeyu_conv_id cookie。 小部件在初始化时写入它；检查 DevTools → Application → Cookies 中的 WP 站点源。如果不存在，小部件可能从未在聊天页面上加载（见上面的 "小部件未在网站上显示"）。
  2. 对话已经应用了不同的代码。 插件的 woocommerce_load_cart_from_session 钩子首先调用 WC()->cart->has_discount($code)，如果已经应用则跳过。WooCommerce 只允许每个唯一代码一个；切换代码需要删除前一个。
  3. Transient 已过期。 待定优惠券存活 15 分钟。如果访客暂存了代码，然后在打开购物车之前关闭浏览器一个小时，transient 就消失了。在聊天中再次点击 Apply。
  4. 优惠券在 WC 管理员中被删除。 插件在应用时通过 new WC_Coupon($code)->get_id() 验证优惠券有效性。如果代码不再映射到优惠券，apply 调用返回 400 invalid_coupon。

弃购触发器从未触发

  • cart-state.js 未加载。 打开 DevTools → Sources，搜索 hukeyu-cart-state。脚本仅在检测到 WooCommerce 且插件已配置时才排队。
  • localStorage 已禁用。 私有浏览、Safari ITP 或硬化的浏览器配置文件可能会阻止 localStorage.setItem。脚本静默捕获异常 — 没有错误 UI。触发器需要 localStorage；通过添加不同的主动规则（例如 time 或 idle）优雅降级。
  • WC 触发非 jQuery 事件。 一些自定义 WC 主题（Flatsome 的快速查看、AJAX 添加到购物车插件）跳过标准的 jQuery added_to_cart 事件。脚本的 DOM-click 回退覆盖具有 .add_to_cart_button / .single_add_to_cart_button 类名的按钮 — 如果您的主题使用不同的类名，则不会记录购物车状态。添加内联 shim 或提出问题。
  • 触发器的 idle_minutes 阈值未达到。 小部件每 30 秒轮询一次，并在 now - timestamp > idle_minutes * 60_000 ms 时触发。5 分钟阈值意味着在触发器认为购物车被放弃之前，必须经过至少 5 分钟的零购物车事件。仔细检查规则的 conditions.idle_minutes。
  • 全局触发器冷却时间。 小部件对所有主动规则强制执行 5 分钟冷却时间，因此访客不会在每个页面转换时被伏击。触发一个规则，其他规则在 5 分钟内都不会触发。

HMAC 验证失败（插件 REST）

hukeyu → 插件调用返回 401，带有 { "error": { "code": "signature_mismatch" } }。 插件通过 error_log 记录 "Plugin REST HMAC mismatch"。 原因，按顺序：

  1. WP 服务器时钟与 UTC 偏差超过 5 分钟。 运行 date -u。与 https://time.is 比较。如果偏差 > 5 分钟，主机上的 NTP 未运行或损坏。在操作系统级别修复。
  2. 插件的 shopper_signing_secret 与互客鱼的不匹配。 如果您在互客鱼中重新生成 API token（这会滚动新的 shopper_signing_secret）而没有在 WP 中重新运行 "Test connection"，就会发生这种情况。重新点击 Test connection — 插件会静默捕获新的 secret。
  3. WP 端的 signing secret 为空。 返回 plugin_unconfigured 而不是 signature_mismatch。表明插件是从 pre-1.1.0 安装升级的，当时 secret 还不存在。重新点击 Test connection。
  4. 反向代理正在改变请求体。 Cloudflare 的 HTML 重写、像 Wordfence 内联扫描这样的安全插件以及某些 mod_security 规则可以在传输中改变 JSON 体。HMAC 是在原始字节上计算的，所以任何改变都会破坏签名。从重写/扫描规则中排除 /wp-json/hukeyu/v1/*。

RTL 站点在错误的边缘显示小部件

插件在小部件脚本标签上发出 data-page-dir="rtl" 和 data-page-locale。小部件读取它们并在阿拉伯语、希伯来语、 波斯语和乌尔都语区域设置上将栏镜像到视口的右边缘。

  • 检测到错误的区域设置？ 检查 WP 的 Settings → General → Site Language。插件尊重 determine_locale()（它尊重每个用户的覆盖）并回退到 get_locale()。
  • 自定义小部件皮肤？ 如果您通过 Customize 覆盖了小部件的 CSS，您的自定义规则可能没有 RTL 变体。在 DevTools 中检查 .hukeyu-bar — 当页面是 RTL 时，它应该设置了 dir="rtl"。

插件管理员显示 "WooCommerce not detected" 警告，即使 Woo 已激活

在 v2.0.0+ 上这是不可能的 — 插件推迟到 woocommerce_loaded。 如果您在旧安装上看到此问题，请升级到 v2.0.0。v1.x bug 的症状：

  • 设置页面上缺少产品同步按钮。
  • 优惠券发射为空（从未同步任何代码）。
  • 购物车优惠券 REST 端点返回 400 woocommerce_inactive，即使 Woo 在 /shop 中正常运行。

阅读插件日志

插件通过 hukeyu\Support\Logger 写入 error_log。 要在典型的 WordPress 安装上查看它们：

  1. 在 wp-config.php 中将 WP_DEBUG_LOG 设置为 true。
  2. 插件的事件显示在 wp-content/debug.log 中，前缀为 [hukeyu]。
  3. 值得注意的行："Plugin REST HMAC mismatch"、"PostSyncer batch failed"、"CouponSyncer hydrate failed"、"Lead user create failed"。

在哪里提出问题

如果以上都没有解决您的问题，请提出问题并提供：

  • 插件版本（在 wp-plugin/hukeyu/hukeyu.php 顶部或插件管理员中可见）。
  • WordPress 版本 + PHP 版本（在 Tools → Site Health → Info → WordPress 中可见）。
  • WooCommerce 版本（如果适用）。
  • 活动的页面构建器及其版本（如果适用）。
  • 相关的 wp-content/debug.log 尾部。
  • 最小重现：您点击了哪个按钮，您期望什么，发生了什么。