WoodMart 与缓存插件兼容性配置

一、为什么需要兼容性配置

⚠️ 缓存插件和 WoodMart 的 AJAX 功能（加入购物车、产品筛选、快速查看、迷你购物车等）天生存在矛盾：

• 缓存插件想把所有页面保存为静态 HTML，提高速度
• AJAX 功能需要动态响应，不能被缓存

如果缓存配置不当，会出现：
– 🛒 加入购物车没反应
– 🔍 产品筛选不工作
– 👁️ 快速查看弹窗不弹出
– 📱 移动端页面显示错误的布局

本篇讲的就是如何在「快」和「能用」之间找到平衡。

---

二、排除 WooCommerce 关键页面缓存

🚫 2.1 必须排除缓存的页面

以下页面绝对不能被缓存，否则会导致用户功能异常：

页面	URL 路径	排除原因
购物车页	/cart/	购物车内容每个用户不同
结账页	/checkout/	结账信息每个用户不同
我的账户	/my-account/	账户信息每个用户不同
愿望清单	/wishlist/	愿望清单每个用户不同
对比页	/compare/	对比内容每个用户不同

💡 前三个页面（购物车、结账、我的账户）是 WooCommerce 的标准页面，主流缓存插件都会自动识别并排除。真正需要你手动处理的，是 WoodMart 特有的愿望清单页和对比页。

🚀 2.2 WP Rocket 排除方法

WP Rocket 检测到 WooCommerce 后，会自动排除 Cart、Checkout、My Account 三个页面，无需手动添加。你需要做的只有两件事：

1. 进入 设置 → WP Rocket → 高级规则（Advanced Rules）。
2. 在 Never Cache URL(s)（永不缓存的 URL）中手动添加 WoodMart 特有的动态页面：

/wishlist/
/compare/

1. 在 Never Cache Cookies（永不缓存的 Cookie）中输入：

woocommerce_cart_hash
woocommerce_items_in_cart
wp_woocommerce_session_
woocommerce_recently_viewed

1. 保存设置。

💡 最后一条 woocommerce_recently_viewed 对应「最近浏览的产品」功能，不排除的话用户看到的浏览记录可能是缓存的旧数据。

🐆 2.3 LiteSpeed Cache 排除方法

LiteSpeed Cache 通过内置的 Third Party（第三方兼容）模块自动检测 WooCommerce：自动把购物车、结账、我的账户页面标记为不缓存，并把 woocommerce_items_in_cart、woocommerce_cart_hash 注册为缓存变体（cache-vary）触发器。不需要、也没有”WooCommerce 集成开关”，检测是全自动的。

你要做的是核对与补充：

1. 进入 LiteSpeed Cache → Cache → Excludes，检查 Do Not Cache URIs 中是否已包含 /cart/、/checkout/、/my-account/（通常已自动加入，插件或 WooCommerce 更新后建议复查）。
2. 手动添加 WoodMart 特有的动态页面：
3. /wishlist/
4. /compare/（如启用了对比功能）
5. 保存设置。

---

三、JS/CSS 延迟加载排除

⏳ 3.1 延迟加载的风险

缓存插件的「延迟加载 JS（Delay JavaScript Execution）」功能可以显著提升页面初始加载速度，但可能导致 WoodMart 的 AJAX 功能在用户首次交互时失效。

📜 3.2 WP Rocket JS 延迟排除

首选方案：用 WoodMart 的内置开关（推荐）

WoodMart 专门为 WP Rocket 做了一个联动开关，会自动把主题核心 JS 文件（加购、AJAX 筛选器、快速查看等）加入 WP Rocket 的延迟排除列表：

1. 进入 主题设置 → Performance → Plugins。
2. 开启 WP Rocket delay JS exclusions。

3. 保存设置，清除缓存后测试前台功能。

补充方案：手动排除

如果开启主题开关后仍有功能异常，进入 设置 → WP Rocket → 文件优化 → Delay JavaScript execution，在 Excluded JavaScript Files 中追加排除：

jquery
jquery-core
/wp-content/plugins/woocommerce/assets/js/
wc-add-to-cart
woocommerce

⚠️ 排除太多 JS 会降低延迟加载的效果。先用主题开关解决，手动清单只作为排查补充——逐个添加、每加一条测试一次，定位到具体冲突的脚本就停手。

🎨 3.3 CSS 延迟排除

如果你开启了 WP Rocket 的 Remove Unused CSS（移除未使用的 CSS），可能需要排除 WoodMart 的关键 CSS：

1. 在 Excluded CSS Files 中添加：

/wp-content/themes/woodmart/
/wp-content/plugins/woodmart-core/

1. 保存设置。

---

四、避免功能冲突

🦥 4.1 懒加载冲突

WoodMart 主题设置中自带图片懒加载功能，缓存插件（WP Rocket、LiteSpeed Cache）也有懒加载功能。两者不能同时开启，否则会导致图片加载异常（WoodMart 官方文档明确警告过多套懒加载系统并行的冲突）。

解决方案（二选一）：

• 方案 A（推荐）：使用 WoodMart 自带的懒加载（Performance → Lazy Loading），关闭缓存插件的懒加载
• 方案 B：使用缓存插件的懒加载，关闭 WoodMart 的懒加载

💡 推荐方案 A，与第十八课的配置保持一致：WoodMart 的懒加载面板还附带背景图懒加载、提前量（Offset）、淡入效果和自定义占位图，颗粒度更细。

🧬 4.2 CSS/JS 合并冲突

WoodMart 和缓存插件都可能提供 CSS/JS 合并功能。如果两者同时合并，可能导致样式或脚本异常。

解决方案：
– CSS 合并：只用缓存插件的合并功能，WoodMart 主题设置中的 CSS 优化保持默认（WoodMart 8.5 默认已做 CSS 内联优化，不需要额外合并）
– JS 合并：只使用缓存插件的 JS 合并功能，如果合并后出现功能异常，关闭 JS 合并

☁️ 4.3 缓存与 AJAX 购物车

开启缓存后，AJAX 加入购物车功能可能因为页面被缓存而失效。解决方法：

1. 确保 WP Rocket 的 Never Cache Cookies 中已排除 WooCommerce 相关 Cookie（见 2.2）。
2. 确保 LiteSpeed Cache 的 WooCommerce 自动排除已生效（见 2.3）。
3. 如果使用 Cloudflare，进入 Caching → Cache Rules，为动态页面创建绕过规则：
4. 匹配条件：URI Path 包含 /cart、/checkout、/my-account、/wishlist
5. 操作：Bypass Cache（跳过缓存）

⚠️ 注意：Cloudflare 旧版的 Page Rules 已废弃，现在统一使用 Cache Rules。如果你按旧教程找 Page Rules 找不到，直接进 Cache Rules 配置即可。完整的 Cloudflare 缓存规则配置见第十八课。

---

五、移动端缓存与 AJAX 兼容性

📱 5.1 移动端单独缓存

WoodMart 的 Mobile DOM optimization 功能会根据设备类型移除不需要的资源。这意味着移动端和桌面端的 HTML 结构不同。

WP Rocket 设置：
1. 进入 设置 → WP Rocket → 缓存。
2. 开启 Separate cache files for mobile devices（为移动设备创建单独缓存）。
3. 开启后，WP Rocket 会为移动端和桌面端分别生成缓存文件。

LiteSpeed Cache 设置：
1. 进入 LiteSpeed Cache → Cache → Mobile。
2. 开启 Cache Mobile（移动端缓存）。
3. 默认的 Mobile User Agent 列表已覆盖主流移动设备，一般无需修改。

⚠️ 如果不开启移动端单独缓存，移动端用户可能看到桌面端缓存的内容，导致 WoodMart 的 Mobile DOM optimization 输出错误页面结构。

🧪 5.2 AJAX 兼容性测试

开启缓存后，在移动端逐项测试以下功能：

功能	测试方法	正常状态
加入购物车	点击产品页的「加入购物车」	迷你购物车更新，无页面刷新
产品筛选	在商店页点击筛选条件	产品列表更新，无页面刷新
快速查看	在产品网格点击快速查看	弹窗正常弹出
迷你购物车	点击页眉购物车图标	购物车面板展开，内容正确
变体切换	在可变产品页选择属性	价格和图片更新
搜索	使用页眉搜索框搜索	搜索结果正常显示

⚠️ 如果某个功能在缓存开启后失效，先清除缓存测试是否恢复正常。如果正常，说明是缓存规则问题，回到对应章节调整排除规则。

---

六、兼容性配置检查清单

检查项	检查方式	目标状态
购物车页排除缓存	访问 /cart/ 页面	页面未被缓存（每次刷新内容不同）
结账页排除缓存	访问 /checkout/ 页面	页面未被缓存
愿望清单排除缓存	访问 /wishlist/ 页面	页面未被缓存
加入购物车	点击加购按钮	AJAX 正常工作
产品筛选	在商店页筛选	AJAX 正常工作
快速查看	点击快速查看	弹窗正常
移动端单独缓存	用不同设备访问	移动端显示正确布局
懒加载不冲突	查看图片加载	只有一个懒加载在工作
变体切换	在可变产品页切换属性	价格和图片正确更新