Skip to main content

Liquid 模板语言

Liquid 是驱动每个 Shopify 在线商店主题的模板语言。由 Shopify 联合创始人 Tobias Lutke 创建，Liquid 使用商店数据在服务器端渲染 HTML。无论你是构建主题、创建应用区块，还是为商家自定义店面，理解 Liquid 都是必不可少的。本课程涵盖语言基础、主题架构和性能最佳实践。

Liquid 基础​

Liquid 有三个构建块：对象、标签和过滤器。

对象​

对象输出数据。它们用双花括号包裹：

{{ product.title }}
{{ product.price | money }}
{{ shop.name }}
{{ customer.first_name }}

对象由 Shopify 根据当前页面上下文提供。在产品页上，product 可用。在系列页上，collection 可用。全局对象如 shop、cart 和 settings 在所有页面都可用。

标签​

标签创建逻辑和控制流。它们用花括号加百分号包裹：

{% if product.available %}
  <button type="submit">Add to Cart</button>
{% else %}
  <button disabled>Sold Out</button>
{% endif %}

{% for product in collection.products %}
  <div class="product-card">
    <h3>{{ product.title }}</h3>
    <p>{{ product.price | money }}</p>
  </div>
{% endfor %}

{% unless customer %}
  <a href="/account/login">Log in for exclusive pricing</a>
{% endunless %}

常用标签包括：

标签用途
if / elsif / else条件逻辑
for遍历数组
unless否定条件
case / whenSwitch 语句
assign创建变量
capture将输出捕获到变量中
render引入代码片段
section渲染一个 Section
form生成 Shopify 表单
paginate分页系列
comment代码注释（不渲染）

过滤器​

过滤器修改对象的输出。它们用管道符 | 分隔：

{{ "hello world" | capitalize }}
<!-- 输出: Hello world -->

{{ product.price | money_with_currency }}
<!-- 输出: $29.99 USD -->

{{ product.title | handleize }}
<!-- 输出: premium-widget -->

{{ product.description | strip_html | truncate: 150 }}
<!-- 输出: 前 150 个字符，无 HTML -->

{{ "now" | date: "%B %d, %Y" }}
<!-- 输出: March 30, 2026 -->

Shopify 提供了数十个电子商务专用过滤器：

<!-- 货币格式化 -->
{{ 2999 | money }}                    → $29.99
{{ 2999 | money_with_currency }}      → $29.99 USD
{{ 2999 | money_without_trailing_zeros }} → $29.99

<!-- 图片处理 -->
{{ product.featured_image | image_url: width: 400 }}
{{ product.featured_image | image_url: width: 800, height: 600, crop: 'center' }}

<!-- URL 生成 -->
{{ product | product_url }}
{{ "cart" | link_to: routes.cart_url }}

<!-- 数组操作 -->
{{ collection.products | where: "available", true | size }}
{{ collection.products | sort: "price" | first }}
{{ collection.products | map: "title" | join: ", " }}

主题架构​

Shopify 主题是 Liquid 文件、资源和配置的结构化集合。理解文件结构至关重要。

theme/
├── layout/
│   └── theme.liquid              # 主布局包装器
├── templates/
│   ├── index.json                # 首页模板
│   ├── product.json              # 产品页模板
│   ├── collection.json           # 系列页模板
│   ├── page.json                 # 自定义页面模板
│   ├── blog.json                 # 博客模板
│   ├── article.json              # 文章模板
│   ├── cart.json                 # 购物车页模板
│   ├── 404.json                  # 404 页面
│   ├── search.json               # 搜索结果
│   └── customers/
│       ├── account.json          # 客户账户
│       ├── login.json            # 登录页面
│       └── order.json            # 订单详情
├── sections/
│   ├── header.liquid             # 网站头部
│   ├── footer.liquid             # 网站底部
│   ├── featured-collection.liquid
│   ├── product-info.liquid
│   └── rich-text.liquid
├── snippets/
│   ├── product-card.liquid       # 可复用产品卡片
│   ├── price.liquid              # 价格显示逻辑
│   └── icon-cart.liquid          # SVG 图标
├── assets/
│   ├── theme.css
│   └── theme.js
├── config/
│   ├── settings_schema.json      # 主题设置定义
│   └── settings_data.json        # 当前设置值
└── locales/
    ├── en.default.json           # 英语翻译
    └── fr.json                   # 法语翻译

布局​

布局文件（layout/theme.liquid）包裹每个页面。它包含 <html>、<head> 和 <body> 标签以及 {{ content_for_header }} 和 {{ content_for_layout }} 标签：

<!DOCTYPE html>
<html lang="{{ request.locale.iso_code }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{ page_title }} — {{ shop.name }}</title>
  {{ content_for_header }}
  {{ "theme.css" | asset_url | stylesheet_tag }}
</head>
<body>
  {% sections "header-group" %}

  <main id="MainContent" role="main">
    {{ content_for_layout }}
  </main>

  {% sections "footer-group" %}

  <script src="{{ 'theme.js' | asset_url }}" defer></script>
</body>
</html>
content_for_header 是必需的

{{ content_for_header }} 标签注入 Shopify 必需的脚本——分析、App Bridge、结账集成等。永远不要移除此标签，否则你的主题将会出错。

JSON 模板​

在 Online Store 2.0 中，模板是 JSON 文件，定义哪些 Section 出现以及它们的顺序。这是主题编辑器工作的基础：

{
  "name": "Product",
  "sections": {
    "main": {
      "type": "product-info",
      "settings": {
        "show_vendor": true,
        "show_sku": false
      },
      "blocks": {
        "title": {
          "type": "title",
          "settings": {}
        },
        "price": {
          "type": "price",
          "settings": {
            "show_compare_at": true
          }
        },
        "variant_picker": {
          "type": "variant_picker",
          "settings": {
            "picker_type": "button"
          }
        },
        "buy_buttons": {
          "type": "buy_buttons",
          "settings": {
            "show_dynamic_checkout": true
          }
        },
        "description": {
          "type": "description",
          "settings": {}
        }
      },
      "block_order": ["title", "price", "variant_picker", "buy_buttons", "description"]
    },
    "recommendations": {
      "type": "related-products",
      "settings": {
        "heading": "You may also like",
        "products_to_show": 4
      }
    }
  },
  "order": ["main", "recommendations"]
}

Section 和 Section Schema​

Section 是 OS 2.0 主题的核心构建块。每个 Section 是一个自包含的 Liquid 文件，具有自己的标记、样式、设置和区块。

{% comment %} sections/featured-collection.liquid {% endcomment %}

<div class="featured-collection" style="padding: {{ section.settings.padding }}px 0;">
  <div class="page-width">
    {% if section.settings.heading != blank %}
      <h2 class="section-heading">{{ section.settings.heading }}</h2>
    {% endif %}

    {% assign collection = collections[section.settings.collection] %}

    <div class="product-grid" style="
      display: grid;
      grid-template-columns: repeat({{ section.settings.columns }}, 1fr);
      gap: 24px;
    ">
      {% for product in collection.products limit: section.settings.products_to_show %}
        {% render 'product-card', product: product %}
      {% endfor %}
    </div>
  </div>
</div>

{% schema %}
{
  "name": "Featured Collection",
  "tag": "section",
  "class": "featured-collection-section",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Heading",
      "default": "Featured Collection"
    },
    {
      "type": "collection",
      "id": "collection",
      "label": "Collection"
    },
    {
      "type": "range",
      "id": "products_to_show",
      "min": 2,
      "max": 12,
      "step": 1,
      "default": 4,
      "label": "Products to show"
    },
    {
      "type": "range",
      "id": "columns",
      "min": 2,
      "max": 5,
      "step": 1,
      "default": 4,
      "label": "Columns"
    },
    {
      "type": "range",
      "id": "padding",
      "min": 0,
      "max": 100,
      "step": 4,
      "default": 40,
      "unit": "px",
      "label": "Section padding"
    }
  ],
  "presets": [
    {
      "name": "Featured Collection"
    }
  ]
}
{% endschema %}

底部的 {% schema %} 块定义了：

  • settings：在主题编辑器中显示的配置选项
  • blocks：Section 内可重复的子组件
  • presets：添加 Section 时显示的默认配置
  • templates：此 Section 可以在哪些页面类型上使用
Schema 设置类型

Shopify 支持多种设置类型：text、textarea、richtext、image_picker、url、video、color、font_picker、collection、product、blog、page、link_list、range、select、checkbox、radio、number、html 和 liquid。每种类型在主题编辑器中渲染特定的输入控件。

Liquid 中的元字段​

元字段允许你将自定义数据附加到 Shopify 资源。在 Liquid 中，你通过 metafields 属性访问它们：

<!-- 访问产品元字段 -->
{{ product.metafields.custom.warranty_years.value }}

<!-- 在条件逻辑中使用元字段 -->
{% if product.metafields.custom.is_featured.value == true %}
  <span class="badge badge--featured">精选</span>
{% endif %}

<!-- 渲染元字段图片 -->
{% assign hero_image = product.metafields.custom.hero_image.value %}
{% if hero_image %}
  {{ hero_image | image_url: width: 1200 | image_tag: class: 'hero-image' }}
{% endif %}

<!-- 遍历列表元字段 -->
{% assign ingredients = product.metafields.custom.ingredients.value %}
{% if ingredients %}
  <ul class="ingredient-list">
    {% for ingredient in ingredients %}
      <li>{{ ingredient }}</li>
    {% endfor %}
  </ul>
{% endif %}

要使元字段在主题编辑器中可用，请将其添加到你的 Section Schema：

{
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Heading"
    }
  ],
  "blocks": [
    {
      "type": "metafield",
      "name": "Custom Metafield",
      "settings": [
        {
          "type": "text",
          "id": "metafield_key",
          "label": "Metafield key",
          "info": "Format: namespace.key"
        }
      ]
    }
  ]
}

性能优化​

主题性能直接影响转化率。Shopify 提供了工具和最佳实践来保持主题快速运行。

核心原则​

  1. 最小化 Liquid 循环：每次迭代都是服务器端处理时间。在 for 循环上使用 limit。
  2. 延迟加载图片：在 image_tag 上使用 loading: 'lazy' 参数。
  3. 预加载关键资源：对首屏图片和字体使用 <link rel="preload">。
  4. 延迟加载 JavaScript：在 script 标签上使用 defer 或 async。
  5. 减少 Section 嵌套：深度嵌套的 Section 会增加渲染时间。
<!-- 好的做法：延迟加载首屏以下的图片 -->
{{ product.featured_image | image_url: width: 600 | image_tag:
    loading: 'lazy',
    widths: '200,400,600,800',
    sizes: '(max-width: 600px) 100vw, 50vw'
}}

<!-- 好的做法：预加载首屏英雄图片 -->
<link
  rel="preload"
  as="image"
  href="{{ section.settings.hero_image | image_url: width: 1400 }}"
  media="(min-width: 750px)"
>

主题检查器​

Shopify 的主题检查器是一个 Chrome DevTools 扩展，用于分析 Liquid 渲染时间：

  1. 从 Chrome 网上应用店安装
  2. 打开你的店面并打开 DevTools
  3. 导航到 Shopify 选项卡
  4. 查看 Liquid 渲染的火焰图

检查器显示哪些 Section、代码片段和 Liquid 操作消耗最多的服务器时间。将你的优化工作集中在最热的代码路径上。

避免 Liquid 中的 N+1 查询

一个常见的性能错误是在循环中访问元字段或相关资源而没有设置限制。每次访问都可能触发数据库查询。Shopify 通过缓存来缓解这个问题，但保持循环紧凑并使用 limit 仍然很重要。

<!-- 差：无限制的循环访问元字段 -->
{% for product in collection.products %}
  {{ product.metafields.custom.badge.value }}
{% endfor %}

<!-- 好：限制循环 -->
{% for product in collection.products limit: 12 %}
  {{ product.metafields.custom.badge.value }}
{% endfor %}

要点总结​

  • Liquid 有三种结构：对象（输出数据）、标签（逻辑）和过滤器（转换输出）
  • OS 2.0 主题使用JSON 模板，引用带有 Schema 定义的 Section
  • Section 是主要构建块——带有设置和区块的自包含组件
  • 元字段扩展数据模型，可在 Liquid 和主题编辑器中访问
  • 性能优化重点关注限制循环、延迟加载图片和延迟加载 JavaScript
  • 主题检查器 Chrome 扩展对于分析渲染时间至关重要

接下来，我们将探索 Hydrogen —— Shopify 的 React 无头店面框架。