shopify theme check --output json --fail-level error: Eksiksiz CI Rehberi

shopify theme check --output json --fail-level error komutunu çalıştırmak, temanızdaki her Liquid ve JSON sorununa ilişkin makine tarafından okunabilir bir denetim sağlar ve hata düzeyinde bir sorun bulunur bulunmaz 1 koduyla çıkar. Bu çıkış kodu, GitHub Actions, GitLab CI veya herhangi bir pipeline'da sert bir kapı olarak işlev görür: kırık bir derleme kötü bir dağıtımı durdurur. Çoğu rehberin atladığı şey, JSON çıktısının kendisiyle ne yapacağınız ve neden bu sorunlar sadece kodunuzun kalitesine değil, aynı zamanda yapay zeka arama görünürlüğünüze de zarar verir.

Başlıca Noktalar

• --fail-level error (varsayılan), hata düzeyinde herhangi bir bulgu olduğunda 1 koduyla çıkar; --fail-level suggestion daha katıdır ve daha fazla sorun yakalar.
• --output json ihlallerin yapılandırılmış bir dizisini path, severity, check, message, start_row ve start_column alanlarıyla yayınlar; bunu betiklere veya panolara aktarabilirsiniz.
• {% schema %} bloklarındaki ve settings_schema.json'deki JSON hataları da yapılandırılmış veri hatalıdır: temanızın otomatik olarak yayınladığı Ürün JSON-LD'sini bozarlar.
• Shopify CLI 4.0 (Mayıs 2026 yayınlandı) Node 22.12+ ve Git 2.28+ gerektirir ve paket yöneticisi aracılığıyla otomatik yükseltme yapılır; ancak CI ortamlarında otomatik yükseltmeyi atlar.
• Theme check hatalarını düzeltmek birinci adımdır; bu şablonların ürettiği işlenmiş JSON-LD'yi denetlemek, yapay zeka arama görünürlüğü için eşit derecede önemli ayrı bir adımdır.

Komut Aslında Ne Yapar

shopify theme check, temanızın ve tema uygulama uzantılarının içindeki Liquid ve JSON için bir linterdir. Hataları algılar ve Liquid en iyi uygulamalarını uygular; her hata, sorunları hızlı bir şekilde hata ayıklamak için başarısız kontrolün belgelerine bir bağlantı içerir.

En çok önem verdiğiniz iki bayrak:

Bunları bir araya getirmek:

shopify theme check --output json --fail-level error . > theme-check-results.json

Bu, her bulguyu theme-check-results.json'a yazar ve herhangi bir hata mevcut ise 1 kodu ile çıkar; bu tam olarak CI sisteminizin birleştirmeyi veya dağıtımı engellemek için ihtiyaç duyduğu sinyaldir.

CLI 4.0'dan (Mayıs 2026) itibaren, araç paket yöneticisi aracılığıyla otomatik olarak yükseltilir ancak CI içinde yükseltmeyi atlar ve artık Node 22.12+ ile Git 2.28+ gerektirir. Pipeline çalıştırıcınız daha eski bir Node sürümündeyse, komut bir dosyayı taramadan önce başarısız olur.

JSON Çıktısını Nasıl Okuyacaksınız

Çıkış dizisindeki her öğe bir ihlali temsil eder ve şunu içerir:

• path - sorunun bulunduğu dosya (örn. sections/main-product.liquid)
• check - kontrol adı (örn. ValidJSON, MissingRequiredTemplateFiles, JSONSyntaxError)
• severity - hata için 0, uyarı için 1, öneriler için 2 (dize ve tamsayı formları eşdeğerdir)
• message - insan tarafından okunabilir bir açıklama
• start_row / start_column - dosyadaki tam yer

Shell pipeline'da minimal bir ayrıştırma:

cat theme-check-results.json | jq '[.[] | select(.severity == 0)] | length'

Bu, hata düzeyinde bulguları sayar. Bu sayıyı bir Slack bildiriminde, bir PR yorumunda veya bir pano metriğinde kullanın.

GitHub Actions için pratik CI kod parçacığı:

- name: Theme Check
  run: |
    shopify theme check --output json --fail-level error . > /tmp/tc.json
    echo "Errors: $(jq '[.[] | select(.severity==0)] | length' /tmp/tc.json)"
  env:
    SHOPIFY_FLAG_STORE: ${{ secrets.SHOPIFY_FLAG_STORE }}
    SHOPIFY_CLI_THEME_TOKEN: ${{ secrets.SHOPIFY_CLI_THEME_TOKEN }}
    SHOPIFY_CLI_NO_ANALYTICS: 1

Not: SHOPIFY_CLI_NO_ANALYTICS=1 telemetriyi sessize alır. CI'da etkileşimli istemleri bastırmak için SHOPIFY_FLAG_FORCE=1 de gereklidir. Her ikisi de temiz, asılmayan bir pipeline çalışması için gereklidir.

En Yaygın Hatalar ve Bunları Nasıl Düzelteceksiniz

Theme check, tahmin edilebilir bir dizi yinelenen sorunu ortaya çıkarır. Üretim pipeline'larında en sık karşılaşılanlar şunlardır:

MissingRequiredTemplateFiles

Bu, layout/theme.liquid, templates/product.json veya templates/gift_card.liquid gibi gerekli şablonlar, theme check'in taradığı dizinden eksik olduğunda tetiklenir. En yaygın nedeni komutu yanlış çalışma dizininden çalıştırmak veya CI'da kısmi bir depo almaktır. Düzeltme: pwd'nin tema kökü olduğunu ve git checkout adımınızın tüm dosyaları aldığını (sığ bir klonı değil) onaylayın.

ValidJSON / JSONSyntaxError

Bu iki kontrol, tema dosyalarında geçersiz JSON tanımlar. JSONSyntaxError özellikle temalardaki geçersiz JSON dosyalarını tanımlar ve bunu devre dışı bırakmak önerilmez. ValidJSON {% schema %} etiketleri ve settings_schema.json'ı içindeki tür uyuşmazlıklarını yakalar; örneğin dize olması gereken bir placeholder alanı bir sayı alır veya bunun tersi. Türü düzeltin, sonra shopify theme check --auto-correct komutunu çalıştırarak linter'in şema JSON'unu güvenle yeniden biçimlendirebilmesine izin verin.

SchemaJsonFormat

Bu kontrol (Theme Check v1.x yalnızca) {% schema %} etiketleri içindeki kötü biçimlendirilmiş JSON'u tanımlar. Theme Check bunu --auto-correct bayrağı kullanarak otomatik olarak düzeltebilir; bu JSON verilerini biçimlendirir. Bu kontrol v2.x'te devre dışı bırakmak güvenlidir; burada biçimlendirme, biçimlendirici tarafından işlenir.

Severity tamsayı ve dize uyuşmazlığı

theme-check:recommended ve theme-check:all yapılandırmaları, ciddiyetleri tamsayılar (0, 1, 2) olarak belirtir. Dize formları (error, warning, suggestion) eşdeğerdir ve .theme-check.yml'de okunabilirlik için tercih edilir. Özel bir yapılandırmada ikisini karıştırmak, ciddiyetin göz ardı edildiği görünen kafa karıştırıcı bir çıktıya neden olur.

Theme Check Hataları Neden AI Arama Görünürlüğünü Bozar

Bu, çoğu CI rehberinin tamamen atladığı kısımdır.

Online Store 2.0 temaları, ürün sayfalarında Product, Offer, BreadcrumbList ve Organization JSON-LD'si otomatik olarak yayınlar. Ancak bu çıktı, bunu oluşturan temel Liquid ve JSON kadar geçerlidir. Bir ValidJSON hatası ürün bölümünüzdeki bir {% schema %} bloğunu bozduğunda, bu sayfadaki işlenmiş Ürün JSON-LD sessizce kırılabilir: Liquid, JSON ortasında bir hata dizesi çıktı verir; bu da yapılandırılmış veri bloğunun tamamını çöker.

Pratik sonuç:

• Google Zengin Sonuçlar: Kötü biçimlendirilmiş bir Offer bloğu ürünü fiyat karşılaştırma yüzeylerinden ve Alışveriş uygunluğundan düşürür.
• Yapay zeka motoru alıntıları: Eksik tanımlayıcı alanları (GTIN, marka, MPN), AI ajanlarının SKU'nuzu rakip mağazalarda eşleştirmesini engeller. Kırık bir AggregateRating bloğu ürünü inceleme ağırlıklı yapay zeka önerilerinden diskalifiye eder.
• BreadcrumbList hataları: position tamsayılarından yoksun bir BreadcrumbList ürünü kategori düzeyinde yapay zeka sorgularından izole eder.

shopify theme check --output json --fail-level error komutunu çalıştırmak, Liquid ve şema katmanı sorunlarını yakalar. Ancak tarayıcılara sunulan işlenmiş JSON-LD'yi doğrulamaz. İkinci bir geçişe ihtiyacınız vardır, canlı sayfa çıktısında.

İki katmanlı denetim yaklaşımı:

1. Theme Check (derleme zamanı): shopify theme check --output json --fail-level error dağıtımı engeller.
2. İşlenmiş şema denetimi (çalışma zamanı): Google Zengin Sonuçları Testi veya yapılandırılmış veri doğrulayıcısı kullanarak canlı URL tarafından yayılan gerçek JSON-LD'yi doğrulayın.

Shopify'ın belgelenen CI modeli bu ayrımı yansıtır: theme check linter kapısıdır, shopify theme push --json dağıtım adımıdır ve şema doğrulaması dağıtım sonrası doğrulamadır.

--fail-level Seviyeleri Karşılaştırması

Doğru başarısızlık düzeyini seçmek, katılık ile gürültü arasında bir dengeleme meselesidir:

Çoğu D2C mağaza için, üretim dalında --fail-level error ve çekme isteklerinde --fail-level warning doğru bileşimdir. Gerçek kırılmaları engeller, aynı zamanda PR incelemelerinin önerilen gürültüsü tarafından bunalmasını engeller.

Bir temayı Shopify Tema Mağazasına gönderiyorsanız, Shopify'ın gözden geçirenleri --fail-level style'ı çalıştırır; bu nedenle yerel kapınız eşleşmelidir.

Tema Sağlığını AI Görünürlüğüne Bağlamak

Temiz bir theme check gereklidir ancak yapay zeka arama görünürlüğü için yeterli değildir. Hem kod kalitesi hem de yapay zeka keşfedilebilirliğini hesaba kattığında üretim hazır bir Shopify tema CI pipeline'ı şöyle görünür:

• Kapı 1 (derleme): shopify theme check --output json --fail-level error hata düzeyinde Liquid veya JSON sorunları olan herhangi bir dağıtımı engeller.
• Kapı 2 (dağıtım): shopify theme push --json doğrulanan temayı gönderir ve tema kimliklerini aşağı akış adımları için JSON olarak döndürür.
• Kapı 3 (dağıtım sonrası): Ana ürün sayfalarında işlenmiş Ürün JSON-LD'sini eksik GTIN, marka, MPN ve geçerli Offer.availability değerleri için doğrulayın.
• Kapı 4 (haftalık): ChatGPT ve Perplexity aracılığıyla istem testleri çalıştırarak yapay zeka motorlarının ürünlerinizi gerçekten alıntı yaptığını (sadece taradığını değil) onaylayın.

Çoğu Shopify takımı Kapı 1 ve 2'ye sahiptir. Kapılar 3 ve 4, rakiplere karşı yapay zeka arama görünürlüğü boşluğunun açıldığı yerdir.

Takımınız dört katmanın tamamını manuel olarak inşa etmeden bu boşluğu kapatmak isterse, AgentRank 25 puanlı yapay zeka hazırlık denetimini ve haftalık istem testlerini sizin için çalıştırır; böylece sonuçlar tüm takımınızın harekete geçebileceği bir panoya açılır.

SSS

shopify theme check'te --fail-level error tam olarak ne anlama gelir?

Varsayılan olarak, Theme Check ciddiyet düzeyine error sahip bir veya daha fazla sorun algılandığında başarısız olur (çıkış kodu 1 döndürür). --fail-level error bayrağı bunu açık hale getirir ve başarısızlık seviyesi bayrağı olmadan shopify theme check çalıştırmaya eşdeğerdir. Daha az kritik ortamlarda daha fazla sorun yakalamak için eşiği warning veya suggestion'a yükseltebilirsiniz.

Neden shopify theme check --output json çıktı dosyası üretmiyor?

--output json bayrağı dosyaya değil, stdout'a yazar. Bunu yeniden yönlendirmeniz gerekir: shopify theme check --output json . > results.json. Komut yazılmadan önce çıkarsa (örneğin eksik Node sürümü nedeniyle), dosya boş veya oluşturulmayacaktır. Shopify CLI 4.0'dan (Mayıs 2026) itibaren Node 22.12+ gereklidir.

shopify theme check'i geçmek JSON-LD yapılandırılmış verimin geçerli olduğunu garanti ediyor mu?

Hayır. Theme Check, Liquid kaynak dosyalarınızı ve şema JSON'unu derleme zamanında doğrular, ancak arama motorları ve yapay zeka tarayıcılarına sunulan JSON-LD'yi işlemez ve doğrulamaz. Bir tema tüm theme check kurallarını geçebilir ve yine de GTIN veya marka gibi katalog alanları Shopify yöneticisinde eksikse veya bir inceleme uygulaması çalışma zamanında kötü biçimlendirilmiş AggregateRating işaretlemesi yayınlarsa, kırık Ürün yapılandırılmış verisi yayınlayabilir.