HUSKY - WooCommerce Product Filter Professional

WooCommerce 产品筛选器在 WP Rocket 和缓存下失效

WooCommerce 产品筛选器在 WP Rocket 或其他优化插件下无法工作时,情况几乎总是一样:登录后一切正常,而访客点击后毫无反应,加载动画一直转圈,或者价格滑块变成了普通的文本框。HUSKY 向两者发送的是同一份代码。区别在于,缓存和 JavaScript 优化通常会跳过已登录的管理员,因此您永远看不到访客实际获得的那个优化后的页面。下文将介绍:如何在一分钟内读懂错误信息,在 WP Rocket、LiteSpeed Cache、Autoptimize、SiteGround Optimizer 和 Cloudflare 中究竟要排除什么,以及如何避免页面缓存以 nonce 错误(nonce error) 破坏 AJAX 筛选。

为什么筛选器对管理员有效,对访客却失效

筛选器的前端并不是单个脚本文件,而是一条必须按固定顺序执行的链条:

  1. jQuery,所有筛选器脚本都依赖它。
  2. 内联设置代码块,输出在页面中(在页面源代码里是 <script id="woof_front-js-before">)。它定义了筛选器所需的变量:woof_current_values、woof_is_ajax、swoof_search_slug、woof_ext_init_functions、安全令牌 woof_front_nonce 等。
  3. 插件文件,位于 /wp-content/plugins/woocommerce-products-filter/:js/front.js(它会读取上述变量)、筛选元素和扩展的脚本,以及 jQuery 附加组件,例如 iCheck(复选框皮肤)、ion.rangeSlider(滑块)和 plainOverlay(加载遮罩)。

优化和缓存会以三种方式破坏这条链条。优化会改变顺序,例如延迟了文件却没有延迟内联代码块,或者反过来。在合并或压缩时,它会移动或重写内联代码块。而页面缓存保存的 HTML 中包含带有效期的数据:安全令牌。大多数缓存和优化插件向已登录用户提供的页面既不缓存也不优化,所以管理员视角只能证明筛选器本身是正常的。

先查看浏览器控制台

在隐私窗口中打开商店,此时您处于未登录状态。按 F12(Mac 上按 Cmd+Option+I),打开控制台(Console)标签页,重新加载页面并点击一个筛选项。第一条红色错误会告诉您该往哪里查。

控制台信息含义
woof_current_values is not defined,woof_is_ajax、swoof_search_slug、woof_ext_init_functions 同理(Firefox:assignment to undeclared variable,Safari:Can't find variable)内联设置代码块没有在 front.js 之前运行:它被延迟、移动、删除或损坏了
jQuery is not definedjQuery 被延迟加载,但需要它的代码却更早运行了
iCheck is not a function、plainOverlay is not a function、ionRangeSlider is not a function附加组件文件没有加载,或者在它之后又加载了第二份 jQuery,替换了 jQuery 对象
woof_husky_txt is not defined文本搜索的数据块被剥离,或与其文件分离了
指向内联代码块的 SyntaxError内联代码块中的代码无效,通常来自插件自己的自定义 JavaScript 字段(见下文)
Identifier 'woof_front_nonce' has already been declared设置代码块运行了两次:优化插件或使用 AJAX 页面过渡的主题重新运行了内联脚本
"nonce error" is not valid JSON页面来自缓存,其安全令牌已过期
Unexpected token '<' ... is not valid JSON服务器用 HTML 回应了筛选请求:PHP 提示、防火墙页面或缓存页面
Bad escaped character in JSON有程序在 AJAX 响应送达浏览器的途中改写了它

如果完全没有错误,但滑块只是普通输入框,分层列表的 + 展开按钮缺失,点击也没有反应:说明脚本还没有运行。“延迟 JavaScript 直到用户交互”这类功能就是这种表现。查看页面源代码并搜索 woof_front:如果脚本标签带有 rocketlazyloadscript 或 litespeed/javascript 之类的 type,就说明有优化插件在拦住它们。如果源代码中根本没有 woof_front,请检查仅在以下网站页面初始化插件(Init plugin on the next site pages only)字段(高级 → 代码):如果其中列出了页面,插件就只会在这些页面加载。

JavaScript 优化中应该排除什么

所有工具的规则都一样:jQuery、内联代码块和插件文件必须保持在一起,并保持原有顺序。只排除 front.js 是一种常见的半吊子修复,不会起作用,因为设置代码块和 jQuery 仍然被延迟。下面这三行就涵盖了全部内容:

/wp-includes/js/jquery/
woocommerce-products-filter
woof_

第一行匹配 jQuery 和 jQuery UI(WooCommerce 风格的价格滑块会用到它)。第二行匹配插件及其扩展的所有文件。第三行匹配内联代码块:它们的 id 以及其中的变量都以 woof_ 开头。优化插件的排除字段通常会把关键词同时与文件 URL 和内联脚本的内容进行匹配。

  • WP Rocket。在文件优化(File Optimization)中,将这几行添加到延迟执行 JavaScript(Delay JavaScript execution)的排除文件中;如果筛选器仍然失效,也请将它们添加到延迟加载 JavaScript(Load JavaScript deferred)的排除项中,或者关闭该选项。如果优化 CSS 交付(Optimize CSS delivery)设置为移除未使用的 CSS,请将插件的样式和 .woof 类添加到其 CSS 安全列表:许多筛选器类只在 JavaScript 运行后才出现,所以对静态页面的扫描会把它们视为未使用。
  • LiteSpeed Cache。JS 合并(JS Combine)和延迟加载 JS(Load JS Deferred)(延迟或推迟)是常见原因;请将这几行添加到 JS 排除项以及延迟/推迟排除项中。如果筛选请求已返回但商品没有刷新,并且控制台显示 Bad escaped character in JSON,请关闭 CDN 映射(CDN Mapping):在已确认的案例中,它改写了 AJAX 响应。
  • Autoptimize。聚合 JavaScript 时,jQuery 会被移到页面末尾的合并文件中,而内联代码仍留在原处,因此运行得太早。请在从 Autoptimize 中排除脚本(Exclude scripts from Autoptimize)中保留 js/jquery/jquery.min.js 和 woocommerce-products-filter。
  • SiteGround Speed Optimizer、WP-Optimize 及类似插件。合并、延迟以及“延迟内联脚本”选项都需要相同的排除项,或者必须关闭。
  • Cloudflare Rocket Loader。它会异步加载所有脚本,包括内联代码块,还会阻止筛选器前端构建器(Filter front builder)扩展启动。请在 Cloudflare 的速度设置中关闭它,然后清除 Cloudflare 缓存。
  • HTML 压缩如果“移除不必要的字符”,可能会损坏内联脚本。请关闭它对内联 JavaScript 的压缩。
  • 挂在 script_loader_tag 过滤器上的主题或代码片段。WordPress 会把内联代码块与脚本标签一起传给这个过滤器,所以在此剥离属性或替换引号的代码可能会破坏它。请移除此类代码,或将其限制在其他句柄上。

筛选器内部的两项设置

AJAX 完成后执行的 JavaScript 代码(JavaScript code after AJAX is done)(WooCommerce → 设置 → Products Filter → 高级 → 代码)会作为函数体插入内联设置代码块。这里的笔误,例如括号未闭合,会破坏整个代码块,所有筛选器变量都会变成“not defined”。可以清空该字段来测试;若要在筛选后运行代码,使用 woof_ajax_done 事件更为稳妥。

优化 HUSKY JavaScript 文件的加载(Optimize loading of HUSKY JavaScript files)(高级 → 选项)用于在两种加载方式之间切换:否(No)会加载 front.js 以及用于单选按钮、复选框和下拉菜单的四个独立脚本;是(Yes)会在页脚加载一个压缩文件 js/front_comprssd.js。有些优化插件的配置只适用于其中一个值。请两个都试一试,每次更改后清除所有缓存。

页面缓存与“nonce error”

在 AJAX 模式下(选项标签页上的尝试将商店 AJAX 化(Try to ajaxify the shop),或 [woof_products is_ajax=1] 页面),以及使用 ajax_redraw 属性时,筛选器会向服务器请求新的商品,并发送取自页面的令牌 woof_front_nonce。服务器会校验它,如果无效,就会以纯文本 nonce 错误(nonce error) 作答。脚本期望得到的是 JSON,无法读取这个回应,于是加载动画一直停留在屏幕上。

令牌是在生成 HTML 时创建的。对于未登录的访客,WordPress 的 nonce 至少有效 12 小时,最多有效 24 小时。来自缓存、比这更旧的页面带着的是失效的令牌。这就是为什么问题会出现在缓存生成一天之后的缓存页面上,也是刷新页面有时有效的原因:恰好命中了一份新的副本。清除缓存只能管几个小时。持久的解决办法:

  • 将 HTML 页面的缓存有效期保持在 12 小时以内。WP Rocket 默认的 10 小时有效期是安全的;在 CDN 上长期缓存 HTML 是典型的元凶。
  • 不要在 CDN 上缓存商店和分类的 HTML。使用 Cloudflare 时,添加一条缓存规则,对商店页、/product-category/ URL 以及任何其他带有筛选器的页面绕过缓存,同时保留遵循自身有效期的 WordPress 页面缓存。只绕过已筛选的 URL 是不够的:访客使用的令牌来自开始筛选的那个页面。
  • 延长这一个令牌的有效时间。自 WordPress 6.1 起,nonce_life 过滤器会接收操作名称,因此可以让筛选器的令牌存活更久,而不影响网站上的其他任何 nonce。该令牌只保护公开的商品列表请求。
/*
 * HUSKY: keep the filter token valid longer than the page cache lifespan.
 * A token is valid for at least half of this time (here: 2 days).
 * Child theme functions.php or a code snippets plugin.
 */
add_filter('nonce_life', function ($life, $action = -1) {
    if ('woof_front_nonce' === $action) {
        return 4 * DAY_IN_SECONDS;
    }
    return $life;
}, 10, 2);

普通的重定向模式(没有 AJAX,也没有 ajax_redraw)完全不使用该令牌:每次筛选变化都会加载一个新的 URL,页面缓存可以像对待其他页面一样提供已筛选的 URL。如果您通过自己的代码调用筛选器,例如向 woof_draw_products 发送自定义 jQuery 请求,请求数据必须包含 nonce_filter: woof_front_nonce,否则即使没有任何缓存,服务器也会回应 nonce 错误(nonce error)。

筛选器内容陈旧及其他缓存副作用

  • 更改后的筛选器设置没有显示出来。这些设置是缓存 HTML 和内联代码块的一部分。保存设置后,请清除每一层缓存:缓存插件、服务器缓存(Varnish、Nginx、主机缓存)、CDN,然后强制刷新浏览器(Ctrl+F5,Mac 上为 Cmd+Shift+R)。
  • 已筛选的链接打开后什么都没选中,或者干净的商店页打开后带着旧的选择。缓存把查询字符串不同的 URL 当成了同一个页面。每个 ?swoof=1&... URL 都必须单独缓存或者不缓存,所以绝不要把缓存设置为忽略商店 URL 上的查询字符串。
  • 手机版筛选器出现在桌面端,或者反过来。筛选器的移动模式和某些扩展会在服务器端根据浏览器的 user agent 决定输出什么。为手机缓存的页面绝不能提供给桌面端:请启用针对移动设备的独立缓存文件。
  • 首次访问某个新的筛选组合会更慢:该 URL 还没有缓存副本。关于整体速度,请参阅加速大型商品目录上的筛选。

安全的测试顺序

  1. 在隐私窗口中、未登录状态下操作,并打开控制台。
  2. 关闭所有 JavaScript 优化(压缩、合并、延迟加载、推迟、Rocket Loader),并清除每一层缓存。如果筛选器现在可以工作,原因就是优化。如果仍然失效,原因在别处:读取第一条控制台错误,并在预发布副本上使用默认主题进行测试。
  3. 逐个重新开启这些选项,每次都清除缓存并测试。一旦某个选项让筛选器失效,就把这三行排除规则添加到该选项中,或者让它保持关闭。
  4. 在 AJAX 模式下,在一个已缓存一天的页面上再次检查筛选器。没有出现 nonce 错误(nonce error),就说明缓存有效期或令牌有效期设置正确。
  5. 除了桌面端,也要在手机上测试,并测试结果的第二页。

如果完成这些步骤后筛选器仍然只对已登录用户有效,请在 HUSKY 支持论坛上发起一个主题,附上页面链接、第一条控制台错误以及您已启用的优化选项清单,我们会进行查看。