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渲染區段
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                  # 找不到頁面
│   ├── 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 檔案，定義了哪些區段出現以及出現順序。這就是佈景主題編輯器運作的原理：

{
  "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"]
}

區段與區段結構描述​

區段是 OS 2.0 佈景主題的核心構建模組。每個區段是一個獨立的 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：區段內的可重複子元件
  • presets：新增區段時出現的預設設定
  • templates：此區段可以使用在哪些頁面類型
結構描述設定類型

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">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 %}

要使中繼欄位在佈景主題編輯器中可用，請將它們新增到您的區段結構描述中：

{
  "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. 減少區段嵌套：深層嵌套的區段會增加渲染時間。
<!-- 好的做法：延遲載入首屏以下的圖片 -->
{{ 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 的 Theme Inspector 是一個 Chrome DevTools 擴充功能，可以分析 Liquid 渲染時間：

  1. 從 Chrome 線上應用程式商店安裝
  2. 開啟您的店面並打開 DevTools
  3. 導覽到 Shopify 分頁
  4. 查看 Liquid 渲染的火焰圖

檢查器顯示哪些區段、片段和 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 模板 來引用帶有結構描述定義的區段
  • 區段是主要的構建模組——包含設定和區塊的獨立元件
  • 中繼欄位擴展資料模型，可在 Liquid 和佈景主題編輯器中存取
  • 效能最佳化著重於限制迴圈、延遲載入圖片和延遲 JavaScript
  • Theme Inspector Chrome 擴充功能是分析渲染時間的必備工具

接下來，我們將探索 Hydrogen——Shopify 用於無頭式店面的 React 框架。