Shopify Theme Check: --path vs Konumsal Argümanlar Açıklaması

Shopify Theme Check konumsal bir argüman olarak tek bir dosya yolunu kabul edemez. shopify theme check sections/hero.liquid komutunu çalıştırmak yalnızca o dosyayı kontrol etmez. Araç her zaman tüm tema ağacını doğrular, ancak birkaç desteklenen teknik nelerin kontrol edileceğini, neyin hatayla çıkacağını ve çıktınızda neyin görüneceğini daraltmanıza izin verir. Theme Check 2.x sürümüyle tanıtılan değişiklikler de dahil olmak üzere işe yarayan her yöntem burada yer almaktadır.

Temel noktalar

• shopify theme check sections/hero.liquid, Theme Check 2.x sürümünde geçersiz söz dizimidir ve hata ile çıkar.
• --path çalışmayı tek bir dosyaya değil, bir alt dizine kapsamı kısıtlar.
• JSON çıktısı (-o json) jq üzerinden iletilen, sonuçları belirli bir dosyaya filtrelemenin tek güvenilir yoludur.
• .theme-check.yml, tüm glob desenlerini yoksayabilir, üçüncü taraf veya oluşturulan dosyalardan gelen gürültüyü bastırır.
• Satır içi {% # theme-check-disable CheckName %} yorumları herhangi bir Liquid dosyası içinde belirli kuralları gizler.
• CLI 4.0 sürümünden beri (Mayıs 2026), Theme Check Node 22.12+ gerektirir ve araç paket yöneticiniz aracılığıyla otomatik olarak güncellenir.

Neden tek dosya argümanı yoktur

Theme Check dosya dosya söz dizimi denetçisi değil, bütün tema linter'ıdır. Kurallarının çoğu tasarım gereği dosyalar arası çalışır: MissingSnippet, bir {% render %} çağrısının tema içinde başka bir yerde gerçek bir dosyaya çözümlü olup olmadığını kontrol eder ve UnusedAssign'in bir değişkeni tüketebilecek her şablonu görmesi gerekir. Bunu tek bir dosyaya karşı yalıtımda çalıştırmak, tam olarak bu kontrollerde yanlış pozitiflere neden olurdu.

Bu tasarım nedeniyle, Shopify'nin resmi CLI belgeleri Theme Check'in tüm tema ağacını analiz etmek için tasarlandığını doğrular. Mevcut CLI'de --file veya --only bayrağı yoktur.

Yöntem 1: Bir alt dizini kapsamak için --path

Tek dosya linting'e en yakın desteklenen yaklaşım --path'dir. Theme Check'e tema kökünün nerede yaşadığını söyler, hangi dosyayı kontrol edeceğini değil. Ancak bunu CI sırasında yaratıcı bir dizin yapısıyla birleştirebilirsiniz:

# Geçerli çalışma dizininden tüm temayı kontrol edin (varsayılan)
shopify theme check

# Bir alt dizin içinde yaşayan bir temayı kontrol edin
shopify theme check --path ./my-theme

Bölümleri klasörü belirli bir PR'de değiştirilen tek kısmı içeriyorsa, --path'i yalnızca değiştirilen dosyaları içeren geçici bir kopyaya işaret edebilirsiniz. Çoğu takım için bu aşırıdır, ancak bir monorepo birden fazla temayı içerdiğinde kullanışlıdır.

--path'in yapmadığı şey: sections/hero.liquid gibi tek bir dosyayı değeri olarak kabul etmez. Dosya yolu değil, bir dizin iletin.

Yöntem 2: Dosya başına filtreleme için jq'ya aktarılan JSON çıktısı

Bu, CI ardışık düzleminde belirli bir sections/*.liquid dosyasını hedeflemek için en pratik yöntemdir. Theme Check'in -o json bayrağı dosya yoluna göre anahtarlanmış bir makine tarafından okunabilen düz dizi yayar. Bunu jq aracılığıyla iletip yalnızca ilgilendiğiniz girişi ayıklamak için:

# Tam kontrol çalıştırın, JSON çıktısı alın, ardından bir dosyaya filtreleyin
shopify theme check -o json \
  | jq '.[] | select(.path == "sections/hero.liquid")'

Filtrelenen sonuca dayanarak kendiniz sıfırdan farklı bir çıkış kodu da belirtebilirsiniz:

ERRORS=$(shopify theme check -o json \
  | jq '[.[] | select(.path == "sections/hero.liquid") | .offenses[] | select(.severity == "error")] | length')

if [ "$ERRORS" -gt 0 ]; then
  echo "hero.liquid has $ERRORS error(s)"
  exit 1
fi

Bu örüntü, var olmayan bir bayrağa gerek duymadan GitHub Actions veya GitLab CI işinizde dosya başına gating eşdeğeri sağlar.

Yöntem 3: .theme-check.yml göz ardı etme desenleri

Amaç belirli bir dosyayı veya klasörü hedeflemek yerine susturmak ise, .theme-check.yml kontrol başına glob tabanlı göz ardı etme listelerini destekler. Üst düzey ignore anahtarını kullanarak tüm kontroller için tüm dizinleri yoksayabilirsiniz:

# .theme-check.yml
TemplateLength:
  enabled: true
  ignore:
    - sections/legacy-*
    - snippets/vendor-*

UnusedAssign:
  enabled: true
  ignore:
    - snippets/replo-*

Başlangıç yapılandırması oluşturun:

shopify theme check --init

Bu, özellikle oluşturulan veya üçüncü taraf dosyaları (Replo snippet'leri gibi) içerdiğiniz durumlarda yararlıdır ve bu dosyalar aksi takdirde theme dev'de LiquidHTMLParsingError'u tetikleyecek olan kasıtlı olarak bölünmüş Liquid'i içerir.

Yöntem 4: Bölümlerde Liquid içindeki satır içi bastırma yorumları

Belirli bir bölüm dosyası içindeki tek seferlik kurallar için, Liquid satır içi yorumları adlandırılan herhangi bir kontrol bölümünü bir kod bloğu etrafında devre dışı bırakmayı ve yeniden etkinleştirmeyi sağlar:

{%- comment -%} Vendor render modelinden yanlış pozitifi bastır {%- endcomment -%}
{% # theme-check-disable UnusedAssign %}
{%- assign hero_context = section.settings.context -%}
{% # theme-check-enable UnusedAssign %}

Bastırma yorumunu ilk satıra yerleştirerek tüm dosya için bir kontrol de bastırabılirsiniz:

{% # theme-check-disable SpaceInsideBraces %}
{%assign x = 1%}

Bu yaklaşım kod incelemesinde görülür (bunu tek satırlık bir fark olarak gösterir) ve tema içindeki başka herhangi bir dosyayı etkilemez.

Yöntem 5: Yerel geliştirme için VS Code onlySingleFileChecks

Amacınız bir bölüm dosyasını etkin olarak düzenlerken editörinizde hızlı geri bildirim almaksa, Shopify Liquid VS Code uzantısının Theme Check'i yalnızca açık dosyayla sınırlayan bir ayarı vardır:

// .vscode/settings.json
{
  "themeCheck.onlySingleFileChecks": true
}

Bu açıkken, dosyalar arası kontroller (MissingSnippet gibi) atlanır ve yalnızca tek dosya kuralları etkin sekmede çalıştırılır. Resmi depo, bunu "geliştirme sırasında birden fazla dosyaya yayılan kontrolleri göz ardı edebilirseniz performans için harika" olarak açıklar. Dosyalar arası sorunları yakalamak için CI'de tam shopify theme check komutunu çalıştırın.

Karşılaştırma: her yöntem yan yana

CLI 4.0 gereksinimleri gözden kaçırmamanız gerekir (Mayıs 2026)

CLI 4.0 Mayıs 2026'da yayımlandığından beri, Theme Check çalıştıran her CI ardışık düzenini etkileyen iki gereksinim değişti:

• Node 22.12+ gereklidir. Eski Node sürümleri sessizce başarısız olur veya beklenmeyen çıktı üretir.
• Araç paket yöneticiniz aracılığıyla otomatik olarak güncellenir ve tasarım gereği CI içinde otomatik güncellemeyi atlar. Sürümünüzü package.json içinde veya CI görüntüsünde açıkça sabitleyin.

Ayrıca bilmesi gerekli olan: --category ve --exclude-category Theme Check 2.x sürümünde kaldırılmıştır (Ocak 2024). Bu bayrakları gösteren eski öğreticiler bulursanız, artık çalışmaz. Tüm kullanılabilir kontrolleri açıkça çalıştırmak için -C theme-check:all kullanın.

CI geçit deseni: ardışık düzende Theme Check'i çalıştırmanın doğru yolu

Shopify'nin kendi belgeleri tarafından önerilen idiomatik ardışık düzen dizilişi:

# 1. Hataları kontrol edin (ve çoğu takım tarafından varsayılan olarak göz ardı edilen uyarılar)
shopify theme check --fail-level warning

# 2. Önizleme için yayımlanmamış bir geliştirme temasına gönderin
shopify theme push --unpublished --json

# 3. Yalnızca manuel incelemenin ardından yükseltin
shopify theme publish --theme <ID> --force

Kaçınılması gereken iki yaygın hata:

• Varsayılan --fail-level, error anlamına gelir, bu da uyarıların sessizce birikmesi ve CI işinizin hala 0 ile çıkması anlamına gelir. Bunları engel için --fail-level warning iletin.
• theme push üzerindeki --strict de Theme Check iletilmedikçe push'u engeller, bu size dağıtım zamanında ikinci bir güvenlik ağı sağlar.

PR başına önizleme temaları için, shopify theme push --development-context "pr-482" bir geliştirme temasını PR numarası gibi sabit bir tanımlayıcıya bağlar.

Birleştirme: Bölümler Liquid için pratik iş akışı

İşte yukarıdakileri geçtikten sonra çoğu takımın üzerinde durduğu sıra:

1. Editor: bölüm Liquid yazarken hızlı, dosya içi geri bildirim için VS Code'da onlySingleFileChecks özelliğini etkinleştirin.
2. Ön işlem kancası: bir commit ile başlamadan önce tüm tema karşı shopify theme check --fail-level error çalıştırın.
3. CI pull request geçidi: shopify theme check -o json | jq çalıştırarak yalnızca değiştirilen bölüm dosyalarını ayıklayın ve karşı karşıya gelin.
4. CI dağıtım geçidi: shopify theme push --strict çalıştırın, böylece birisi 3. adımı atlasa bile, hatalı bir push engellenir.
5. Yapılandırma: Oluşturulan veya satıcı snippet'lerinden yanlış pozitifler tarafından gerçek çalışmayı durdurmaktan önlemek için hedeflenen göz ardı etme glob'larıyla bir .theme-check.yml dosyası koruyun.

Bunu gerçek bir ardışık düzene bağlamak için yardım mı gerekiyor? Shopify tema geliştirici hizmetleri sayfası, bunu müşteri projeleri için nasıl kurduğumla ilgili bağlam sağlar ve Shopify hız optimizasyonu Theme Check'in en sık bayrak kaldırdığı performans kontrollerini kapsar.

Bu işi dışarıya vermek isteyen mağazalar için Lintel gibi stüdyolar Shopify tema geliştirme hizmeti veriyor.