HUSKY 涡轮模式无法使用:筛选器变灰与产品缺失
HUSKY 涡轮模式无法使用时,症状看起来互不相关:筛选器一直是灰色的,某个分类没有返回任何产品,新产品始终不出现,计数不正确,或者无法关闭 AJAX 模式。几乎所有这些问题都源于同一个设计决定:在涡轮模式下,筛选在访客的浏览器中进行,依据的是预先生成的产品数据文件。下文说明这个文件是如何生成和使用的,并给出每种症状的解决办法。
涡轮模式的工作原理,以及何时值得使用
在普通模式下,每次点击筛选器,服务器都要运行一次 WooCommerce 查询,并为每个术语统计产品数量。涡轮模式把这部分工作转移到浏览器中。HUSKY 会把所有已发布的产品及其变体写入一个 JSON 文件(默认位于 wp-content/uploads/uploads_woof_turbo_mode/),其中包含 ID、标题、SKU、价格、库存状态、每个产品分类法的术语,以及 Meta 筛选字段的值。浏览器会在插件运行的每个前台页面上下载该文件(可以用高级 (Advanced)标签页上的仅在以下站点页面初始化插件 (Init plugin on the next site pages only)限制这些页面),找出匹配的产品并绘制计数;服务器只负责根据 ID 渲染找到的产品。
因此,结果的新旧程度取决于该文件;文件中没有的产品无法被找到;只有浏览器能够理解的条件才会生效;而且每位访客都要下载整个商品目录,在有数万个产品和变体的情况下,这意味着数兆字节的数据,手机上的启动也会很慢。涡轮模式适合服务器性能较弱、商品目录规模适中且很少变动的商店。如果服务器能够胜任这些查询,请先尝试使用普通模式并配合如何在大型商品目录中加快产品筛选速度中介绍的缓存。
按正确的顺序启用
- WooCommerce → 设置 → Products Filter → 扩展 (Extensions):勾选涡轮模式 (Turbo mode)并保存。
- 高级 (Advanced) → 涡轮模式 (Turbo mode):将启用涡轮模式 (Enable turbo mode)设为是 (Yes)并保存。
- 点击立即重新汇总产品数据!(Reassemble products data now!)下方的立即更新!(Update now!),并保持页面打开,直到出现文件已更新!!!(File updated!!!)。没有这个文件,筛选器就无法搜索。
- 选择WordPress 计划任务周期 (WordPress Cron period)和产品数据文件的存放位置 (Where to keep products data file),然后保存。
- 在选项 (Options)标签页中设置显示计数 (Show count)、动态重新计数 (Dynamic recount)和隐藏空术语 (Hide empty terms),它们在涡轮模式下是单独的副本(见下文说明),然后清除页面缓存和所有 CDN 缓存。
筛选器一直是灰色的,无法点击
灰色层是一个类名为 woof_turbo_mode_overlay 的元素。它从一开始就覆盖在筛选器上,涡轮模式脚本会在文件加载完毕并绘制出计数后将其移除。如果这个灰色层一直存在,说明该脚本没有运行完:
- 脚本被延迟、推迟或合并。WP Rocket、LiteSpeed Cache 等插件的优化功能可能会让脚本延后执行、顺序错乱,或者根本不执行。涡轮模式需要
wp-content/plugins/woocommerce-products-filter/中的ext/turbo_mode/js/turbo_mode.js和ext/quick_search/js/alasql/alasql.min.js,并且要在 jQuery 之后加载。请将插件文件夹从延迟、推迟和合并中排除,然后清除所有缓存;筛选器与 WP Rocket 及缓存一文说明了应当排除的内容。 - JavaScript 错误。打开浏览器控制台(F12)并重新加载页面。第一条红色错误会指出是哪个脚本阻止了其余脚本的运行。
- 网速慢时文件过大。在“网络 (Network)”标签页中,查看
data_0000_xxx.json的大小和耗时。如果下载使筛选器灰显数秒之久,说明商品目录对涡轮模式来说太大了。
用 CSS 隐藏该层(.woof_turbo_mode_overlay{display:none;})只是掩盖症状:筛选器虽然可以点击了,但没有加载文件,它仍然无法搜索。
当文件无法加载时,筛选器会被替换为提示糟糕!筛选器似乎无法打开搜索文件。(Oh no! It looks like the filter can't open the search file.)请检查:
- 文件是否存在。保存在插件文件夹(plugins\woocommerce-products-filter\ext\turbo_mode\data)中的文件会在每次插件更新时被删除,因此更新后请重新生成,或者将其保存在 wp-uploads\uploads_woof_turbo_mode 中;
- 是否有服务器规则或安全插件拦截了 uploads 中的
.json文件:直接打开“网络 (Network)”标签页中显示的文件地址进行检查; - 地址是否正确。插件请求的是
wp-content/uploads/uploads_woof_turbo_mode/,因此在多站点的子站点上,或者 uploads 文件夹被移到其他位置时,请求会返回 404。这种情况下请将文件保存在插件文件夹中。
找不到产品,或筛选后产品缺失
涡轮模式只返回文件中存在的产品,并且只依据其中保存的数据进行匹配。请在带有筛选器的页面加载完成后,从浏览器控制台检查这两点:
woof_turbo_mode_file.length // records in the file: products + variations
woof_turbo_mode_file.find(p => p.id == 123) // what is stored for product 123
将第一个数字与您已发布的产品加变体的总数进行比较;使用 WP-CLI 时,wp post list --post_type=product,product_variation --post_status=publish --format=count 可以得到这个数字。如果某个产品返回 undefined,说明它不在文件中。如果它在文件中,请查看它的 taxonomies 和 stock。
文件已过期
新产品、修改过的分类、属性、价格和库存,只有在下一次重新生成之后才会反映到筛选器中。典型的迹象有:新产品显示在商店页面上,但第一次点击筛选器后就消失;新术语的计数为 0;最后几页分页是空的;或者在上次重新生成之后添加的 Meta 筛选元素什么也找不到。导入产品之后,以及更改筛选器元素之后,请重新生成该文件。
15,000 条的上限
立即更新!(Update now!)在处理到 15,000 条记录后就会停止,而变体也计入其中。一个有 2,000 个可变产品、每个有八个变体的商店,已经有 18,000 条记录了。该按钮会优先处理最新的产品,因此被遗漏的是您最旧的产品。如果按钮旁边的计数器停在了产品和变体:15000 (Products and Variants: 15000),说明您达到了上限。请使用 woof_turbo_mode_products_limit 钩子提高上限,然后重新生成:
/*
* HUSKY Turbo mode: let "Update now" write up to 40,000 products and variations.
* Child theme functions.php or a code snippets plugin.
*/
add_filter('woof_turbo_mode_products_limit', function ($limit) {
return 40000;
});
计划任务触发的重新生成不受这个钩子的限制;它会处理整个商品目录。
子分类中的产品找不到
文件只保存每个产品上勾选的分类,浏览器按字面进行比较;它并不了解分类树。WordPress 会在父分类页面中显示子分类的产品,但涡轮模式不会:只在“跑鞋”(Running shoes)下勾选的产品,在第一次点击筛选器之前会显示在“鞋”(Shoes)页面上,之后就消失了,“鞋”筛选术语找不到它,“鞋”的计数也不包含它。请在这类产品上勾选整条分类链的每一级(“鞋”和“跑鞋”),例如使用产品 → 所有产品中的批量编辑,然后重新生成文件。
隐藏产品和缺货产品
目录可见性 (Catalog visibility)为仅商店 (Shop only)或隐藏 (Hidden)的产品会被视为在搜索中隐藏,无论遵循目录可见性 (Listen catalog visibility)如何设置,涡轮模式在筛选后都不会返回它们。因此,仅商店 (Shop only)的产品会出现在商店页面上,并在第一次点击后消失;如果它应该可以被筛选,请将其设为商店和搜索结果 (Shop and search results)。启用 WooCommerce 的隐藏目录中缺货的商品 (Hide out of stock items from the catalog)后,缺货产品会被排除在文件之外,而重新有货的产品在下一次重新生成之前仍然是缺失的。
WPML 语言
使用 WPML 时,HUSKY 会为每种语言写入一个文件(data_0000_en.json、data_0000_de.json),并加载当前语言的文件。没有翻译的产品不会出现在该语言的文件中,因此翻译完成后请重新生成。
保持搜索文件最新
立即更新!(Update now!)以每批十个产品或变体的方式生成文件,最多每秒一批,并带有产品和变体 (Products and Variants)计数器。每一批都会重写整个文件,所以 15,000 条记录至少需要 25 分钟。与计划任务触发的重新生成不同,该按钮会先删除当前文件,在它完成之前,网站使用的是不完整的数据进行筛选:请在访问量低的时段运行,保持页面打开,并且不要在中途关闭涡轮模式。
WordPress 计划任务周期 (WordPress Cron period)用于设置自动重新生成:每天 (daily)、每周 (weekly)(默认)、每月两次 (twicemonthly)、每月 (monthly)、每分钟 (min1)或不更新 (without update)。尽管名称如此,这并不是 WP-Cron 事件。HUSKY 使用自己的计划(选项 woof_turbo_init_wpcrone_):当到了该重新生成的时间,每个加载了 WordPress 和该插件的请求(最多每五秒一次)会把接下来的十条记录添加到一个临时文件中,在最后一批完成后,这个临时文件会替换正在使用的文件。在此之前,访客看到的仍是之前的数据。由此可以得出:
- WP Crontrol 等工具不会列出它,
DISABLE_WP_CRON也无法阻止它。 - 速度取决于到达 PHP 的请求;由页面缓存提供的页面不计算在内。20,000 条记录至少需要相隔五秒的 2,000 次请求,也就是接近三小时的持续访问量,而在访问量低的网站上则需要数天。
- 首次自动重新生成发生在您保存计划之后整整一个周期,所以启用之后请点击立即更新!(Update now!)。
- 周期从上一次重新生成结束时开始计算。每分钟 (min1)会在一分钟后开始下一次,因此网站会一直在重新生成;仅将其用于小型商品目录。
- 在自动重新生成期间点击立即更新!(Update now!),也会删除它的临时文件;自动运行完成后,它会用其后生成的那一部分替换您完整的文件。如果在手动重新生成数小时后产品又缺失了,请再点击一次该按钮。
在访问量低的网站上,可以用服务器 cron 任务来提供这些请求;常见问题自动 cron 更新失败的原因介绍了设置方法和 PHP 限制。请每分钟调用一次,而不是每天一次,因为每次调用只添加一批。如果您用仅在以下站点页面初始化插件 (Init plugin on the next site pages only)限制了插件,请让它请求 /wp-admin/admin-ajax.php,插件在该地址上始终会加载。即便如此,每小时也只能添加 600 条记录,所以对于会批量变动的商品目录,请在每次导入之后点击立即更新!(Update now!)。
可以使用 woof_turbo_mode_schedules 钩子添加其他周期,无需修改插件文件;然后选择新的周期并保存:
/*
* HUSKY Turbo mode: add "every 12 hours" to WordPress Cron period.
* Child theme functions.php or a code snippets plugin.
*/
add_filter('woof_turbo_mode_schedules', function ($schedules) {
$schedules['every_12_hours'] = array(
'name' => 'every 12 hours',
'value' => 12 * HOUR_IN_SECONDS,
);
return $schedules;
});
每次重新生成后,文件的地址保持不变。如果 CDN 或浏览器缓存了 .json 文件,访客可能会一直收到旧数据:请将 uploads_woof_turbo_mode 文件夹排除在 CDN 缓存之外,或在每次重新生成后清除它。
涡轮模式依赖 AJAX,并有自己的计数设置
启用涡轮模式期间,HUSKY 会在每次加载页面时重置四项设置:尝试将商店 AJAX 化 (Try to ajaxify the shop)变为是 (Yes),而常规的显示计数 (Show count)、动态重新计数 (Dynamic recount)和隐藏空术语 (Hide empty terms)变为否 (No)。此时选项 (Options)标签页会以相同的名称显示涡轮模式自己的这三项副本,其中动态重新计数 (Dynamic recount)提供是,适用于所有设备 (Yes, for all devices)或是,仅限电脑 (Yes, only for PC)。
- 涡轮模式开启时无法关闭 AJAX。请先将启用涡轮模式 (Enable turbo mode)设为否 (No)并保存,然后再更改尝试将商店 AJAX 化 (Try to ajaxify the shop)。
- 如果主题的产品网格在 AJAX 筛选后出现错乱(每行一个产品、列数丢失、分页损坏),涡轮模式也会继承这些问题:请参阅在 AJAX 模式下设置列数和 AJAX 模式下的分页问题,或者对该主题保持涡轮模式关闭。
- 关闭涡轮模式之后,请重新设置显示计数 (Show count)、动态重新计数 (Dynamic recount)和隐藏空术语 (Hide empty terms):它们仍然是否 (No),这就是计数器在那一刻消失的原因。
- 隐藏空术语 (Hide empty terms)只有在显示计数 (Show count)和动态重新计数 (Dynamic recount)都开启时才有效;关闭显示计数 (Show count)会同时关闭另外两项。
- 涡轮模式开启时,缓存筛选器中每个项目的动态重新计数数值 (Cache dynamic recount number for each item in filter)、缓存术语 (Cache terms)和优化价格筛选 (Optimize price filter)会从“高级 → 选项”中消失;它们不适用于涡轮模式。
涡轮模式做不到的事
- 层级下拉列表 (Hierarchy drop-down)元素无法与它配合使用,如涡轮模式扩展页面所列。
- 计数和隐藏空术语 (Hide empty terms)适用于标准元素(复选框、单选按钮、下拉列表、颜色、图片、标签、滑块)。用 Smart Designer 构建的元素没有计数。
- 有货 (In stock)只看每个产品自身的库存状态;检查变体的那项设置不起作用,因此按尺码筛选时仍然可能显示缺货的变体。
- 文本搜索只将输入的词与产品标题进行比较,即使文本搜索元素被设置为在描述或其他字段中查找也是如此。单独的 SKU 元素可以使用。
- 用 PHP 添加的条件不参与搜索,因为由浏览器决定哪些产品匹配。作用于
woof_products_query或pre_get_posts的自定义代码、自定义扩展,以及按供应商或客户组限制产品的插件,最多只能在事后隐藏部分已找到的产品,这会使计数和分页不一致。
如果您的商店需要其中任何一项,或者价格和库存每小时都在变化,请关闭涡轮模式,改用缓存来加快普通模式的速度。
检查清单
- 控制台中没有红色错误;插件的脚本已从延迟、推迟和合并中排除。
woof_turbo_mode_file.length与已发布产品加变体的数量一致;计数器没有停在上限处。- 在上一次导入或筛选器更改之后已重新生成文件;页面缓存和 CDN 已清除。
- 产品已在整条分类链上勾选,且可见性为商店和搜索结果 (Shop and search results)。
- 计数设置已在涡轮模式的副本中设置,并在关闭涡轮模式后再次设置。
如果筛选器仍然工作异常,请在 HUSKY 支持论坛上发起一个主题,并附上页面链接、控制台错误、woof_turbo_mode_file.length 的值,以及您的产品和变体数量。