Shopify Theme Check: Belirli Dosya Yollarını ve Sections Liquid Dosyalarını Hedefleme

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ı linter tarafından kontrol etmeyecektir. Araç her zaman tüm tema ağacını doğrular, ancak kontrol edilecek öğeleri, hata çıkışını ve çıktıda görünen öğeleri daraltmanıza olanak sağlayan birkaç desteklenen teknik vardır. Theme Check 2.x'te sunulan değişiklikler dahil olmak üzere çalışan her yöntemi burada bulabilirsiniz.

Temel noktalar

• shopify theme check sections/hero.liquid Theme Check 2.x'te geçersiz söz dizimidir ve bir hatayla çıkar.
• --path çalıştırmayı bir dizine kapsamlandırır, tek bir dosyaya değil.
• JSON çıktısı (-o json) jq aracılığıyla yönlendirilen, sonuçları belirli bir dosyaya filtrelemek için tek güvenilir yoldur.
• .theme-check.yml tüm glob desenlerini göz ardı edebilir, üçüncü taraf veya oluşturulan dosyalardan gelen gürültüyü susturabilir.
• Satır içi {% # theme-check-disable CheckName %} yorumları herhangi bir Liquid dosyasında belirli kuralları bastırır.
• CLI 4.0'dan bu yana (Mayıs 2026), Theme Check Node 22.12+ gerektirir ve araç paket yöneticiniz aracılığıyla kendini otomatik olarak günceller.

Neden tek dosya argümanı yok

Theme Check, dosya dosya söz dizimi denetleyicisi değil, tam tema linter'ıdır. Birçok kuralı tasarım gereği çapraz dosyalıdır: MissingSnippet, bir {% render %} çağrısının temada başka bir yerde gerçek bir dosyaya çözümlenip çözümlenmediğini kontrol eder ve UnusedAssign değişkeni tüketebilecek her şablonu görmesi gerekir. Bunu tek bir dosyaya karşı yalıtımda çalıştırmak, tam olarak bu kontrollerden yanlış pozitifler üretecektir.

Bu tasarım nedeniyle, Shopify'ın resmi CLI belgeleri, Theme Check'in tam tema ağacını analiz etmesi anlamına geldiğini doğrular. Mevcut CLI'de --file veya --only bayrağı yoktur.

Yöntem 1: Bir alt dizini kapsamlandırmak için --path

Tek dosya linting'in 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 yaklaşmak için CI sırasında yaratıcı bir dizin yapısıyla bunu birleştirebilirsiniz:

# Mevcut çalışma dizininden tüm temayı lint edin (varsayılan)
shopify theme check

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

Sections klasörü verilen bir PR'de değişen tek bölümse, --path'i yalnızca değiştirilmiş dosyaları içeren geçici bir kopya gösterebilirsiniz. Bu çoğu ekip için aşırı olmakla birlikte, bir monorepo birden fazla tema içerdiğinde yararlıdır.

--path'in yapamadığı şey: sections/hero.liquid gibi tek bir dosya path'ini değer olarak kabul etmez. Dosya yolu değil dizin geçirin.

Yöntem 2: jq için JSON çıktısı dosya başına filtreleme

Bu, bir CI boru hattında belirli bir sections/*.liquid dosyasını hedeflemek için en pratik yöntemdir. Theme Check'in -o json bayrağı, dosya yoluyla anahtarlanan makine tarafından okunabilir düz bir dizi yayar. Bunu jq aracılığıyla yönlendirerek yalnızca önemsediğiniz girişi çıkartın:

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

Filtrelenmiş sonuca dayalı olarak kendiniz sıfır olmayan bir çıkış kodu da onaylayabilirsiniz:

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 model, var olmayan bir bayrak gerektirmeden, GitHub Actions veya GitLab CI işinizde dosya başına gating'in eşdeğerini sağlar.

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

Hedef belirli bir dosya veya klasörü hedeflemek yerine susturmak ise, .theme-check.yml kontrol başına glob tabanlı göz ardı listelerini destekler. Ayrıca ignore üst düzey anahtarını kullanarak tüm denetimlerden tüm dizinleri göz ardı edebilirsiniz:

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

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

Başlangıç yapılandırmasını şu komutla oluşturun:

shopify theme check --init

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

Yöntem 4: Sections Liquid içinde satır içi bastırma yorumları

Belirli bir section dosyasının içindeki tek seferlik kurallar için, Liquid satır içi yorumları, kod bloğunun etrafında herhangi bir adlandırılmış kontrolü devre dışı bırakmanıza ve yeniden etkinleştirmenize izin verir:

{%- comment -%} Suppress false positive from vendor render pattern {%- endcomment -%}
{% # theme-check-disable UnusedAssign %}
{%- assign hero_context = section.settings.context -%}
{% # theme-check-enable UnusedAssign %}

Ayrıca, disable yorumunu ilk satıra yerleştirerek tüm dosya için bir kontrolü bastırabilirsiniz:

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

Bu yaklaşım kod incelemesinde görünür (bir satırlık fark olarak gösterilir) ve temadaki başka bir dosyayı etkilemez.

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

Amacınız, etkin olarak bir section dosyasını düzenlerken editöründe hızlı geri bildirim almaksa, Shopify Liquid VS Code eklentisinin Theme Check'i yalnızca açık dosyayla sınırlandıran bir ayarı vardır:

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

Bu açıkken, çapraz dosya kontrolleri (MissingSnippet gibi) atlanır ve geliştirme sırasında yalnızca tek dosya kuralları etkin sekmede çalışır. Resmi depo, bunu "çapraz dosya kontrolleri geliştirme sırasında yok sayabilirseniz [sizin için] harika performans" olarak tanımlar. Çapraz dosya sorunlarını yakalamak için CI'de tam shopify theme check'i çalıştırın.

Karşılaştırma: tüm yöntemler yan yana

CLI 4.0 gereklilikleri gözardı etmemelisiniz (Mayıs 2026)

CLI 4.0 Mayıs 2026'da piyasaya çıktığından beri, Theme Check'i çalıştıran her CI boru hattını etkileyen iki gereksilik 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 kendini günceller ve tasarım gereği CI içinde otomatik yükseltmeyi atlar. package.json'de veya CI resminizde sürümü açıkça sabitleyin.

Bilmek de değerli: --category ve --exclude-category Theme Check 2.x'te kaldırıldı (Ocak 2024). Bu bayrakları gösteren eski öğreticiler bulursanız, artık çalışmaz. Tüm mevcut kontrolü açıkça çalıştırmak için -C theme-check:all kullanın.

CI gate deseni: boru hattında Theme Check'i çalıştırmanın doğru yolu

Shopify'ın kendi belgeleri tarafından önerilen idiomatik boru hattı dizisi şu şekildedir:

# 1. Hatalara karşı kapı (ve uyarılara, çoğu ekip varsayılan olarak göz ardı eder)
shopify theme check --fail-level warning

# 2. Önizleme için yayınlanmamış bir geliştirme temasına itin
shopify theme push --unpublished --json

# 3. Yalnızca manuel incelemeden sonra yükseltin
shopify theme publish --theme <ID> --force

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

• Varsayılan --fail-level error'dır, bu da uyarılar sessizce birikir ve CI işiniz yine de 0 ile çıkar. Onları engellemek için --fail-level warning geçirin.
• theme push'daki --strict ayrıca Theme Check geçmediği sürece push'u engeller, bu da dağıtım zamanında size 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 stabil bir tanımlayıcıya bağlar.

Bir araya getirme: sections Liquid için pratik iş akışı

Yukarıdaki adımlardan geçtikten sonra çoğu ekibin bitirdiği dizi şöyledir:

1. Editör: VS Code'da onlySingleFileChecks'i etkinleştirin, section Liquid yazarken hızlı, dosya içi geri bildirim için.
2. Ön commit hook: commit gitmeden önce tüm tema karşısında shopify theme check --fail-level error çalıştırın.
3. CI çekme isteği kapısı: shopify theme check -o json | jq çalıştırın, yalnızca değiştirilmiş section dosyalarını çıkartın ve onaylayın.
4. CI dağıtım kapısı: shopify theme push --strict çalıştırın, böylece biri adım 3'i atlasa bile, hatalar içeren bir push engellenir.
5. Yapılandırma: herhangi bir oluşturulan veya satıcı snippet'leri için hedeflenen ignore glob'ları içeren bir .theme-check.yml koruyun, yanlış pozitiflerden gerçek işi durdurmak.

Bunu gerçek bir boru hattına entegre etmeye yardıma mı ihtiyacınız var? Shopify tema geliştirici hizmetleri sayfasının bu konuya nasıl ayarladığım hakkında bağlamı vardır ve Shopify hız optimizasyonu Theme Check'in en sık işaretlediği performans kontrollerini kapsar.