如何调试 Shopify Liquid：完整指南

I’m happy to translate the article for you, but I need the full text you’d like translated. Could you please paste the content (excluding the source line you already provided) so I can convert it to Simplified Chinese while preserving the formatting and code blocks?

为什么 Liquid 难以调试？

Liquid 是一种模板语言，而不是编程语言。它在 Shopify 的基础设施上服务器端运行，这意味着：

这些因素使调试成为一个缓慢、令人沮丧的反复试验过程。

方法 1：json 过滤器

最常用的调试技巧是将对象输出为 JSON。

{{ product | json }}

在 HTML 中将整个 product 对象渲染为 JSON 字符串。

然后你可以：

• 查看页面源代码或检查元素。
• 复制 JSON 输出。
• 粘贴到 JSON 格式化工具中阅读。

限制

• 会使 HTML 输出变得杂乱。
• 容易忘记并留在生产代码中。
• 每次更改都需要刷新页面。
• 大对象难以浏览。
• 没有语法高亮或搜索功能。

更佳做法：包装在 <script> 标签中

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

现在你可以在浏览器的 DevTools 控制台中查看格式化后的数据。

方法二：Shopify Theme Check

Theme Check 是 Shopify 官方的 Liquid 代码检查工具。它在部署前捕获常见错误。

安装

# 通过 Shopify CLI
shopify theme check

# 或者独立使用
gem install theme-check
theme-check

它能捕获的内容

• 未定义的对象和变量。
• 已废弃的标签和过滤器。
• 缺失的模板文件。
• 性能问题（例如，API 调用过多）。
• 翻译键错误。

限制

• 仅进行静态分析——无法捕获运行时错误。
• 不能检查实际的数据值。
• 在终端运行，而非浏览器中。
• 没有实时调试功能。

方法 3：Shopify 的内置错误信息

Liquid 会直接在 HTML 输出中显示某些错误。查找类似以下信息：

Liquid error: undefined method 'title' for nil:NilClass

Liquid syntax error: Unknown tag 'endfor'

如何查找

1. 查看页面源代码（Cmd+U / Ctrl+U）。
2. 搜索 “Liquid error” 或 “Liquid syntax”。
3. 错误信息通常会指示出文件和行号。

常见错误模式

方法 4：预览检查器（主题编辑器）

Shopify 的主题自定义工具包括一个基本检查器：

1. 打开主题自定义工具。
2. 点击一个区块。
3. 查看可用的设置和块。

限制

• 仅显示区块设置，不显示 Liquid 对象。
• 无法检查产品、购物车或集合数据。
• 不支持表达式求值。
• 无错误检测。

方法 5：浏览器 DevTools（用于 JavaScript）

如果你的 Liquid 输出的数据供 JavaScript 使用，你可以调试 JavaScript 端。

<script>
  window.productData = {{ product | json }};
</script>

然后，在浏览器控制台中：

console.log(productData.title);
console.log(productData.variants[0].price);

限制

• 仅对你显式暴露的数据有效。
• 不能访问仅限 Liquid 的对象，如 template 或 request。
• 需要修改代码以暴露数据。

方法 6：浏览器内 Liquid 开发工具

最全面的解决方案是使用在浏览器中运行的专用开发者工具。

Shopify Theme Devtools 是一个开源面板，提供以下功能：

对象检查器

在可折叠的树形视图中浏览所有 Liquid 对象：

• shop – 商店设置、货币、地区
• product – 当前商品及其变体、图片、元字段
• collection – 包含商品的集合数据
• cart – 实时购物车状态，包括商品和属性
• customer – 已登录的客户数据
• template – 当前模板名称和目录
• request – 页面 URL、主机、路径

点击任意属性即可复制其 Liquid 路径。

实时表达式求值器

在不刷新页面的情况下测试 Liquid 表达式：

> product.title
"Classic Cotton T-Shirt"

> product.price | money
"$29.99"

> cart.items | size
3

> product.variants | first | json
{"id":12345,"title":"Small / Blue",...}

支持 50 多种 Liquid 过滤器，包括 money、money_with_currency、img_url、asset_url 等。

自动错误检测

扫描页面中的常见 Liquid 问题：

综合使用

1. 首先使用 json 过滤器 进行快速数据检查。
2. 在本地运行 Theme Check 以捕获静态问题。
3. 留意渲染后 HTML 中的内置 Liquid 错误信息。
4. 使用预览检查器 进行章节级调试。
5. 在需要调试客户端逻辑时，将数据暴露给 JavaScript。
6. 利用 Shopify Theme Devtools 获得完整功能的浏览器内调试体验。

通过组合这些方法，你可以显著减少排查 Liquid 错误的时间，发布更可靠的 Shopify 主题。祝调试愉快！

购物车调试

• 查看包含所有商品及属性的实时购物车状态
• 在面板内直接调整数量，无需离开页面
• 保存并恢复购物车快照
• 查看带时间戳的购物车历史记录

安装

npx shopify-theme-devtools init --inject

然后按 Cmd+Shift+D（Mac）或 Ctrl+Shift+D（Windows）打开。

仅在开发主题上加载——可安全提交到代码库。

常见 Liquid 错误及解决方案

1. “undefined method for nil:NilClass”

原因: 访问不存在对象的属性。

{{ product.title }}

解决办法: 先检查对象是否存在。

{% if product %}
  {{ product.title }}
{% endif %}

2. “Unknown tag”

原因: Liquid 标签名称拼写错误。

{% end if %}
{% endif %}

3. Drop object leak (#ProductDrop:0x...)

原因: 输出 Liquid 对象时未使用 json 过滤器。

// Bad
const product = {{ product }};

// Good
const product = {{ product | json }};

4. “Could not find snippet”

原因: 渲染了不存在的 snippet。

{% render 'non-existent-snippet' %}

解决办法: 检查 snippet 文件名并确保它位于 snippets/ 文件夹中。

5. Empty output (no error)

原因: 变量为 nil 或为空；Liquid 会静默输出空内容。

调试: 使用 json 过滤器查看实际值。

{{ my_variable | json }}

6. “Invalid JSON in schema”

原因: Section schema 中的 JSON 格式错误。

{% schema %}
{
  "name": "My Section",
  "settings": [
    {
      "type": "text",
      "id": "title"
      
      "label": "Title"
    }
  ]
}
{% endschema %}

解决办法: 在 JSON 验证工具中校验你的 JSON。

7. Incorrect money formatting

原因: 使用原始价格值而未使用 money 过滤器。

{{ product.price }}
{{ product.price | money }}

8. Array index out of bounds

原因: 访问了不存在的数组索引。

{{ product.images[2].src }}

解决办法: 先检查数组大小。

{% if product.images.size > 2 %}
  {{ product.images[2].src }}
{% endif %}

Source: …

调试工作流：一步一步的过程

当你遇到问题时，请遵循以下流程：

步骤 1：检查可见错误

在页面源代码中搜索 “Liquid error” 或 “Liquid syntax error”。

步骤 2：隔离问题

注释掉代码块，直到错误消失：

{% comment %}
  {{ potentially_broken_code }}
{% endcomment %}

步骤 3：检查数据

使用 JSON 输出或开发者工具面板查看实际可用的数据：

{{ product | json }}

步骤 4：验证对象是否存在

在有问题的代码周围添加存在性检查：

{% if product %}
  {% if product.metafields.custom.size > 0 %}
    {{ product.metafields.custom | json }}
  {% else %}
    <!-- 没有自定义 metafields -->
  {% endif %}
{% else %}
  <!-- 没有 product -->
{% endif %}

步骤 5：逐步测试表达式

将复杂表达式拆分为更小的部分：

{{ product.metafields.custom.c }}