[!info] related notes

• 前置笔记: Liquid 模板引擎
• 相关 MOC: Shopify MOC

Liquid 模板常见错误排查

现象

开发 Shopify 主题时遇到的常见 Liquid 错误，包括：

• 页面显示空白或部分内容缺失
• 控制台显示 Liquid 语法错误
• 变量未按预期显示

常见错误与解决方案

1. 标签未正确关闭

错误代码：

{% if product.available %}
  <button>Add to Cart</button>
<!-- 忘记 {% endif %} -->

错误信息：

Liquid syntax error: 'if' tag was never closed

解决方案：

{% if product.available %}
  <button>Add to Cart</button>
{% endif %}

检查清单：

• 每个 {% if %} 必须有对应的 {% endif %}
• 每个 {% for %} 必须有对应的 {% endfor %}
• 每个 {% case %} 必须有对应的 {% endcase %}

2. 变量引用错误

错误代码：

{{ product.name }}  <!-- ❌ 应该是 product.title -->

现象：页面显示空白，无错误提示

解决方案：

{{ product.title }}  <!-- ✅ 正确 -->

调试技巧：输出整个对象查看可用属性

{{ product | json }}

3. 访问不存在的对象

错误代码：

{{ customer.email }}  <!-- 用户未登录时 customer 为 nil -->

现象：不会报错，但可能导致页面布局错乱

解决方案：先检查对象是否存在

{% if customer %}
  <p>Welcome, {{ customer.email }}</p>
{% else %}
  <a href="/account/login">Login</a>
{% endif %}

4. 过滤器拼写错误

错误代码：

{{ product.price | currency }}  <!-- ❌ 应该是 money -->

错误信息：

Liquid error: Unknown filter 'currency'

解决方案：

{{ product.price | money }}  <!-- ✅ 正确 -->

常见过滤器：

• money - 格式化货币
• upcase / downcase - 大小写转换
• strip_html - 去除 HTML 标签
• date: "%Y-%m-%d" - 日期格式化

5. 循环中访问错误

错误代码：

{% for product in collection %}
  {{ product.title }}  <!-- ❌ collection 是集合对象，不是产品数组 -->
{% endfor %}

解决方案：

{% for product in collection.products %}
  {{ product.title }}  <!-- ✅ 正确 -->
{% endfor %}

6. 字符串拼接错误

错误代码：

{{ 'Hello' + customer.name }}  <!-- ❌ Liquid 不支持 + 拼接 -->

解决方案：

{{ 'Hello ' | append: customer.name }}  <!-- ✅ 使用 append 过滤器 -->

<!-- 或者直接写在一起 -->
Hello {{ customer.name }}

7. 条件判断语法错误

错误代码：

{% if product.price > 100 && product.available %}  <!-- ❌ 应该用 and -->
  <p>Expensive and available</p>
{% endif %}

解决方案：

{% if product.price > 100 and product.available %}  <!-- ✅ 使用 and -->
  <p>Expensive and available</p>
{% endif %}

Liquid 逻辑运算符：

• and - 且
• or - 或
• == - 等于
• != - 不等于
• >, <, >=, <= - 比较

8. 嵌套标签错误

错误代码：

{% if product.available %}
  {% for variant in product.variants %}
    {{ variant.title }}
  {% endif %}  <!-- ❌ 应该先关闭 for -->
{% endfor %}

解决方案：

{% if product.available %}
  {% for variant in product.variants %}
    {{ variant.title }}
  {% endfor %}  <!-- ✅ 先关闭内层 -->
{% endif %}

9. 注释语法错误

错误代码：

// This is a comment  <!-- ❌ 不是有效的 Liquid 注释 -->

解决方案：

{% comment %}This is a comment{% endcomment %}

<!-- 或使用简短语法（某些版本支持） -->
{# This is a comment #}

10. 忘记转义特殊字符

错误代码：

<p>Price: ${{ product.price }}</p>  <!-- ❌ $ 与 {{ 冲突 -->

解决方案：

<p>Price: {{ product.price | money }}</p>  <!-- ✅ 使用 money 过滤器 -->

调试技巧

1. 输出变量内容

{{ product | json }}

在浏览器中查看完整对象结构

2. 检查变量是否存在

{% if product %}
  Product exists
{% else %}
  Product is nil
{% endif %}

3. 使用浏览器控制台

<script>
  console.log('Product:', {{ product | json }});
</script>

4. 分段注释

逐段注释代码，定位错误位置：

{% comment %}
  {% if product.available %}
    <button>Add to Cart</button>
  {% endif %}
{% endcomment %}

预防措施

1. 使用代码编辑器的 Liquid 插件（如 VS Code 的 Liquid 语法高亮）
2. 启用 Shopify CLI 的实时错误提示
3. 编写代码时始终成对输入标签（先写 {% if %}{% endif %}，再填充内容）
4. 使用 Git 版本控制，便于回滚错误

Related notes

• Shopify MOC
• Liquid 模板引擎
• Shopify 主题