Shopify Liquid 디버깅 방법: 완전 가이드

Source: Dev.to

위 링크에 있는 글을 번역하려면 실제 텍스트를 제공해 주시겠어요?
코드 블록, URL 및 마크다운 형식은 그대로 유지하면서 내용만 한국어로 번역해 드리겠습니다. 텍스트를 복사해서 보내주시면 바로 작업해 드릴게요.

Liquid 디버깅이 어려운 이유는?

Liquid는 프로그래밍 언어가 아니라 템플릿 언어입니다. Shopify 인프라에서 서버 측으로 실행되므로 다음과 같은 제한이 있습니다:

이러한 요인들 때문에 디버깅은 느리고 좌절감을 주는 시행착오 과정이 됩니다.

Method 1: The json Filter

가장 일반적인 디버깅 기법은 객체를 JSON 형태로 출력하는 것입니다.

{{ product | json }}

전체 product 객체를 HTML에 JSON 문자열로 렌더링합니다.

그 다음에 할 수 있습니다:

• 페이지 소스를 보거나 요소를 검사하기
• JSON 출력 결과를 복사하기
• JSON 포맷터에 붙여넣어 읽기

Limitations

• HTML 출력이 어수선해집니다.
• 프로덕션 코드에 남겨두고 깜빡하기 쉽습니다.
• 변경 사항마다 페이지를 새로 고쳐야 합니다.
• 큰 객체는 탐색하기 어렵습니다.
• 구문 강조나 검색 기능이 없습니다.

Better: Wrap in a <script> Tag

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

이제 브라우저 DevTools 콘솔에서 포맷된 데이터를 확인할 수 있습니다.

Method 2: Shopify Theme Check

Theme Check 은 Shopify의 공식 Liquid 린터입니다. 배포 전에 일반적인 오류를 잡아줍니다.

Installation

# Via Shopify CLI
shopify theme check

# Or standalone
gem install theme-check
theme-check

What It Catches

• 정의되지 않은 객체 및 변수.
• 사용 중단된 태그와 필터.
• 누락된 템플릿 파일.
• 성능 문제 (예: API 호출이 너무 많음).
• 번역 키 오류.

Limitations

• 정적 분석만 수행 — 런타임 오류는 잡지 못함.
• 실제 데이터 값을 검사할 수 없음.
• 브라우저가 아니라 터미널에서 실행됨.
• 실시간 디버깅 기능이 없음.

Method 3: Shopify’s Built‑in Error Messages

Liquid은 일부 오류를 HTML 출력에 직접 표시합니다. 다음과 같은 메시지를 찾아보세요:

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

Liquid syntax error: Unknown tag 'endfor'

How to Find Them

1. 페이지 소스 보기 (Cmd+U / Ctrl+U).
2. “Liquid error” 또는 “Liquid syntax”를 검색합니다.
3. 오류 메시지는 보통 파일명과 라인 번호를 알려줍니다.

Common Error Patterns

방법 4: 미리보기 인스펙터 (테마 편집기)

Shopify의 테마 커스터마이저에는 기본 인스펙터가 포함되어 있습니다:

1. 테마 커스터마이저를 엽니다.
2. 섹션을 클릭합니다.
3. 사용 가능한 설정 및 블록을 확인합니다.

제한 사항

• 섹션 설정만 표시하고, Liquid 객체는 표시되지 않습니다.
• 제품, 장바구니, 컬렉션 데이터를 검사할 수 없습니다.
• 표현식 평가가 지원되지 않습니다.
• 오류 감지가 없습니다.

방법 5: 브라우저 DevTools (JavaScript용)

If your Liquid outputs data for JavaScript consumption, you can debug the JavaScript side.

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

Then, in the browser console:

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

제한 사항

• Only works for data you explicitly expose.
• Can’t access Liquid‑only objects like template or request.
• Requires modifying your code to expose data.

방법 6: 브라우저 내 Liquid DevTools

가장 포괄적인 솔루션은 브라우저에서 실행되는 전용 개발자 도구를 사용하는 것입니다.

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",...}

money, money_with_currency, img_url, asset_url 등을 포함한 50개 이상의 Liquid 필터를 지원합니다.

자동 오류 감지

페이지에서 일반적인 Liquid 문제를 스캔합니다:

모두 합쳐서

1. 빠른 데이터 검사를 위해 json 필터부터 시작하세요.
2. 정적 문제를 잡기 위해 로컬에서 Theme Check를 실행하세요.
3. 렌더링된 HTML에서 내장 Liquid 오류 메시지를 확인하세요.
4. 섹션 수준 디버깅을 위해 Preview Inspector를 사용하세요.
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 객체 누수 (#ProductDrop:0x...)

원인: json 필터 없이 Liquid 객체를 출력함.

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

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

4. “Could not find snippet”

원인: 존재하지 않는 스니펫을 렌더링함.

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

해결책: 스니펫 파일명을 확인하고 snippets/ 폴더에 있는지 확인하세요.

5. 빈 출력 (오류 없음)

원인: 변수값이 nil이거나 비어 있음; Liquid가 조용히 아무것도 출력하지 않음.

디버그: 실제 값을 확인하려면 json 필터를 사용하세요.

{{ my_variable | json }}

6. “Invalid JSON in schema”

원인: 섹션 스키마에 잘못된 JSON이 있음.

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

해결책: JSON 검증기에서 JSON을 검증하세요.

7. 잘못된 금액 포맷

원인: money 필터 없이 원시 가격 값을 사용함.

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

8. 배열 인덱스 범위 초과

원인: 존재하지 않는 배열 인덱스에 접근함.

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

해결책: 먼저 배열 크기를 확인하세요.

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

디버깅 워크플로우: 단계별 프로세스

문제를 만나면 다음 과정을 따르세요:

Step 1: 가시적인 오류 확인

페이지 소스에서 “Liquid error” 또는 “Liquid syntax error” 를 검색합니다.

Step 2: 문제 격리

오류가 사라질 때까지 코드 섹션을 주석 처리합니다:

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

Step 3: 데이터 검사

JSON 출력이나 devtools 패널을 사용하여 실제로 어떤 데이터가 사용 가능한지 확인합니다:

{{ product | json }}

Step 4: 객체 존재 확인

문제 코드 주변에 존재 여부 검사를 추가합니다:

{% if product %}
  {% if product.metafields.custom.size > 0 %}
    {{ product.metafields.custom | json }}
  {% else %}
    <!-- No custom metafields -->
  {% endif %}
{% else %}
  <!-- No product -->
{% endif %}

Step 5: 표현식을 단계적으로 테스트

복잡한 표현식을 작은 부분으로 나누어 테스트합니다:

{{ product.metafields.custom.c }}