WooCommerce 与 WoodMart 主题配合（图文教程）

一、分工原则：功能归 WooCommerce，呈现归 WoodMart

记住一句话：钱、货、单的事找 WooCommerce，长什么样的事找 WoodMart。

🧭 1.1 分工对照

事项	在哪里设置
产品价格、库存、税率、运费、支付	WooCommerce → 设置
订单、优惠券、退款、客户数据	WooCommerce 菜单
商店页布局、产品卡片样式、每行几个产品	WoodMart → Theme Settings → Shop
产品详情页布局、图库样式、Sticky 加购条	Theme Settings → Single product
页眉里的购物车图标、迷你购物车	Theme Settings → Header / My account
快速查看、对比、心愿单、色板	Theme Settings → Shop 相关区块

⚠️ 1.2 一个常见的误区

WooCommerce 设置里的 外观（自定义） 选项在 WoodMart 下基本被主题接管。改 外观 → 自定义 → WooCommerce 里的选项很多不生效，不是坏了，是 WoodMart 用自己的 Theme Settings 覆盖了这些样式。改样式请直接去 Theme Settings。

---

二、先确认页面分配没出问题

WooCommerce 的正常运转依赖四个系统页面，WoodMart 负责把它们「画」出来，但页面本身的分配是 WooCommerce 管的。

🔍 2.1 检查方法

进入 WooCommerce → 状态 → 系统状态，检查有没有「页面未设置」的红色警告。正常状态应该是：

• 商店页面（Shop）→ 已指定
• 购物车（Cart）→ 已指定
• 结账（Checkout）→ 已指定
• 我的账户（My account）→ 已指定

– 条款和条件 → 可选，建议指定

如果缺失，到 WooCommerce → 设置 → 高级 → 页面设置 里重新指定，或点「创建默认 WooCommerce 页面」工具重新生成。

⚠️ 导入 WoodMart 演示数据时如果重复导入了多个演示，可能产生两套「Cart / Checkout」页面，WooCommerce 指向了被删的那套，就会出现购物车空白。排查时先查页面分配。

🧩 2.2 区块版还是短代码版

WooCommerce 9.x 之后，新版结账/购物车默认使用区块（Blocks）构建。WoodMart 对区块版购物车/结账的支持在持续跟进，但如果你发现 WoodMart 的某些购物车增强功能（如迷你购物车联动、免费运费进度条）不生效，检查页面内容是区块还是短代码：

• 编辑购物车/结账页面，看内容是「WooCommerce Cart/Checkout 区块」还是 [woocommerce_cart] / [woocommerce_checkout] 短代码
• 需要用主题增强功能时，把页面内容替换为短代码版本通常能立即恢复

---

三、WoodMart 主题里的 WooCommerce 设置入口

Theme Settings 里和电商直接相关的板块：

🏪 3.1 Shop（商店）

控制商店归档页的一切：布局（网格/列表）、每行产品数、分页方式、Off-canvas 筛选侧栏、AJAX 筛选器、分类展示样式、产品卡片悬停效果。

📄 3.2 Single product（产品页）

• 布局与图库：大图/紧凑/图库聚焦布局，缩略图位置，图片缩放或 Photoswipe 灯箱

• Add to cart 区块：AJAX 加购、Sticky 加购条、按钮前后插入自定义 HTML Block
• 标签页：标准标签页或手风琴式，可增删自定义标签
• 单个产品覆盖：编辑产品时的 Product Settings 标签可以为单个产品覆盖全局设置

🛒 3.3 Cart / Checkout（购物车 / 结账）

免费运费进度条、结账页布局（单列/双列）、侧边栏位置、返回商店链接等。

👤 3.4 My account（我的账户）

登录/注册页样式、账户仪表盘布局、社交登录等扩展。

💡 Theme Settings 右上角有搜索框，直接搜关键词（如 “cart”、”checkout”）比逐个翻板块快得多。

---

四、主题增强功能与原生功能的关系

这是最容易混乱的部分。逐个说清：

⚡ 4.1 AJAX 加购：原生只管一半

WooCommerce 原生 AJAX 加购只在归档页（商店、分类、标签页）生效，开关在 WooCommerce → 设置 → 产品 → 常规 → Enable AJAX add to cart buttons on archives。

产品详情页加购默认仍是整页刷新。WoodMart 在 Theme Settings → Single product → Add to cart → AJAX Add to cart 里补上了这一块。建议两边都开。

⚠️ 注意：如果某个插件往加购表单里加了自定义字段，AJAX 加购可能失效——这是 WooCommerce 官方文档也标注的限制，排查时先停用该类插件验证。

🔍 4.2 Quick View 与 Quick Shop：纯主题功能

• Quick View（快速查看）：在归档页弹出产品简览窗口

– Quick Shop（快速选购）：可变产品不用进详情页，直接在归档页选规格加购

这两个是 WoodMart 独有，WooCommerce 原生没有，也不需要在 WooCommerce 设置里找开关。

🎨 4.3 色板（Swatches）：替换原生下拉框

WooCommerce 原生变体选择是下拉框。WoodMart 在 Theme Settings → Shop → Variable products 里把颜色、尺寸属性渲染成色板和按钮。第 04、05 篇建好的属性会直接被主题接管展示，不需要额外插件。

❤️ 4.4 心愿单、对比、Frequently Bought Together

全部是主题内置模块，在 Theme Settings 对应区块开关。装了第三方同类插件会重复——比如同时开心愿单插件和 WoodMart 心愿单，产品页会出现两个「加入心愿单」按钮，保留一个即可。

🗂️ 4.5 Catalog mode（目录模式）

Theme Settings 里开启后隐藏加购按钮和价格，把商店变成纯展示目录，适合 B2B 询价站。这是主题层开关，WooCommerce 本身不知道这个模式存在。

---

五、模板覆盖与更新：为什么会「样式错乱」

WoodMart 通过覆盖 WooCommerce 的 PHP 模板来实现定制样式。这个机制是主题深度整合电商的标准做法，但也带来一个维护点：

📋 5.1 检查模板版本

进入 WooCommerce → 状态 → 系统状态 → Templates（模板），这里列出 WoodMart 覆盖的所有 WooCommerce 模板。

• 显示绿色/无警告：模板版本匹配，正常
• 标红提示「模板版本过旧」：WooCommerce 升级后，主题里的旧模板可能不兼容新功能

🔄 5.2 过旧怎么办

不要手动改。WoodMart 更新频繁，主题更新日志里几乎每次都包含「UPDATED: WooCommerce templates」。发现模板过旧：

1. 先把 WoodMart 主题更新到最新版（更新前备份，见 WoodMart 系列更新篇）
2. 更新后刷新系统状态页确认警告消失
3. 如果你自己在子主题里覆盖过 WooCommerce 模板，手动比对新版文件同步修改

⚠️ 模板过旧还继续用，轻则新字段不显示，重则结账页报错。看到警告尽快更新主题，别拖。

---

六、冲突排查通用流程

「样式错乱」「按钮不显示」「加购没反应」——按这个顺序查，能解决 90% 的问题：

🧪 6.1 第一步：分清是谁的问题

临时切换到默认主题（如 Storefront），问题还在 → 是 WooCommerce 或插件问题，与 WoodMart 无关；问题消失 → 是主题层问题，去 Theme Settings 找对应开关。

🧹 6.2 第二步：清三层缓存

样式改了不生效，几乎都是缓存：

1. 缓存插件页面缓存（WP Rocket 等）
2. 服务器/CDN 缓存（宝塔、Cloudflare）
3. 浏览器缓存（Ctrl + F5 强制刷新）

🔌 6.3 第三步：插件二分法

停用一半插件测试，逐步缩小范围，定位冲突插件。重点怀疑对象：

• 同类功能插件（另一个心愿单、另一个快速查看）
• 结账字段编辑类插件（可能破坏 AJAX 加购）
• JS 优化类插件（合并/延迟 JS 可能打乱 WoodMart 脚本加载顺序，把 WoodMart 的 JS 加入排除列表）

📝 6.4 第四步：看日志

• WooCommerce → 状态 → 日志：致命错误日志
• 浏览器 F12 → Console：红色 JS 报错，截图留存

都解决不了，带着购买码、日志截图、复现步骤去 XTemos 官方支持论坛提工单。

---

七、常见问题

❓ 7.1 商店页每行产品数改了不生效

你改的很可能是 外观 → 自定义 → WooCommerce → 产品目录——WoodMart 下这里不生效。去 Theme Settings → Shop 改 Products per row / columns。

❓ 7.2 页眉购物车图标点了没反应或不显示数量

• 检查 Theme Settings → Header 里购物车图标的开关和行为设置（跳转/展开迷你购物车）
• JS 优化插件延迟加载导致：把 WoodMart 核心 JS 加入排除列表
• 区块版购物车页面与迷你购物车联动异常：换回短代码版（见 2.2）

❓ 7.3 演示站的功能我的站没有

快速查看、色板、心愿单等都是 Theme Settings 里的开关，演示数据只导入内容不强制开功能。对照演示站逐项在 Theme Settings 里开启即可。

❓ 7.4 结账页布局突然变了

近期是不是更新过 WooCommerce 或 WoodMart？先看 WooCommerce → 状态 → 系统状态 → 模板 有没有过旧警告，再检查结账页面是区块版还是短代码版，两者渲染方式完全不同。

❓ 7.5 主题更新后自定义样式丢了

改在了父主题文件里。所有自定义 CSS 应该放在 Theme Settings → Custom CSS 或子主题 style.css，所有 PHP 修改应该放在子主题 functions.php。父主题的文件一个字都不要动。