产品页面开发

先判断问题出现在哪里

产品详情页（PDP - Product Detail Page）是整个 Shopify 主题中最复杂、交互最密集的页面。它承载了视觉展示、变体选择、价格动态计算和表单提交等核心商业逻辑。

核心逻辑是：状态同步与无缝交互。

当用户在前端点击了一个“红色”的色块，你的 JavaScript 必须瞬间完成三件事：1. 找到对应的变体 ID；2. 更新页面上的价格和库存状态；3. 切换主图到红色的产品图；4. 将隐藏表单中的 Variant ID 更新为红色款的 ID，确保用户点击“加购”时买对东西。这一切必须在毫秒级完成。

实战步骤

步骤 1：构建产品表单 (Product Form)

操作路径：在 sections/main-product.liquid 中编写表单

这是加购的核心。必须使用 Shopify 原生的 {% form 'product' %} 标签。

{% form 'product', product, id: 'product-form-installment' %}
  <!-- 隐藏的 input，用于存储当前选中的变体 ID -->
  <input type="hidden" name="id" value="{{ product.selected_or_first_available_variant.id }}">
  
  <!-- 数量选择器 -->
  <input type="number" name="quantity" value="1" min="1">
  
  <!-- 加购按钮 -->
  <button type="submit" name="add" {% unless product.selected_or_first_available_variant.available %}disabled{% endunless %}>
    {% if product.selected_or_first_available_variant.available %}
      加入购物车
    {% else %}
      已售罄
    {% endif %}
  </button>
{% endform %}

步骤 2：集成多图轮播 (Image Gallery)

操作路径：引入 Swiper.js 或手写原生 CSS Scroll Snap

遍历输出产品图片：

<div class="swiper product-gallery">
  <div class="swiper-wrapper">
    {% for media in product.media %}
      <div class="swiper-slide" data-media-id="{{ media.id }}">
        {% render 'product-media', media: media %}
      </div>
    {% endfor %}
  </div>
  <div class="swiper-pagination"></div>
</div>

注意：不仅要处理图片，还要处理视频（Video）和 3D 模型（Model）。必须使用 product.media 数组而不是 product.images。

步骤 3：编写变体切换的 JavaScript 核心逻辑

操作路径：在 assets/product-info.js 中编写状态机

监听所有变体选项（如尺码、颜色下拉框或单选按钮）的 change 事件。
当选项改变时，获取当前选中的所有选项值（如 ["红色", "XL"]）。
遍历产品的所有变体 JSON 数据，找到匹配这两个选项的特定 Variant 对象。
更新 DOM：
- 将找到的 Variant ID 赋给表单的隐藏 <input name="id">。
- 更新页面上的价格 innerHTML。
- 如果该变体缺货，将加购按钮置灰并修改文字为“Sold Out”。
- 如果该变体绑定了特定的图片（variant.featured_media），调用 Swiper 的 API 切换到对应的图片索引。

步骤 4：实现动态结账按钮 (Dynamic Checkout Buttons)

操作路径：在加购按钮下方插入 Liquid 标签

输出 {{ form | payment_button }}。
Shopify 会自动在这里渲染出 Shop Pay, Apple Pay 或 PayPal 的快捷支付按钮（具体显示哪个取决于用户的浏览器和设备）。
这能极大提升移动端的转化率。

常见误区与处理方法

误区一：将整个产品的 JSON 数据直接暴露在 HTML 中

规避方法：为了在 JS 中方便地查找变体，很多老教程会教你写 <script> var productJson = {{ product | json }}; </script>。这在过去没问题，但在 2026 年，如果你的产品有 100 个变体，这个 JSON 字符串可能会高达几十 KB，直接阻塞页面的首屏渲染。更糟糕的是，它会暴露产品的内部信息（如成本价，如果主题配置不当）。现代的做法是：将变体数据渲染为 HTML 的 data-* 属性，或者只输出一个精简版的 JSON（仅包含 id, options, price, available, featured_media.id），绝对不要把整个庞大的 product 对象直接 | json 输出。

误区二：没有处理 URL 参数的动态更新 (History API)

规避方法：用户在产品页选择了“红色-XL”，然后把当前网页的链接复制发给了朋友。朋友打开链接，看到的却是默认的“黑色-S”。这是因为你只用 JS 在前端切换了状态，没有更新浏览器的 URL。这会导致极差的分享体验和 SEO 问题。在 JS 监听到变体切换并找到目标 Variant ID 后，必须使用 HTML5 的 window.history.replaceState API，将当前的 URL 更新为 ?variant=123456789。这样用户复制的链接就能精准指向他们选中的变体。

误区三：变体切换时价格闪烁或格式错误

规避方法：在 JS 中获取到新变体的价格（如 1999，代表 $19.99）后，很多前端会直接用 JS 拼接字符串：'$' + (price / 100).toFixed(2)。这在单货币、单语言的简单店铺没问题。但如果店铺开启了多货币（如欧元使用逗号作为小数分隔符 19,99 €），这种硬编码的拼接会直接导致价格显示错误。必须使用 Shopify 官方提供的 @shopify/theme-currency 库，或者在页面初始化时从 Liquid 中获取正确的货币格式化模板（Money Format），然后用 JS 进行安全的格式化替换。

FAQ