shopify theme check --path vs Konumsal Argümanlar: Kesin Sözdizimi Rehberi

shopify theme check --path ./your-theme komutunu kullanarak lint çalıştırmasını bir dizine kapsama alın. Mevcut Shopify CLI'da konumsal argüman bulunmamaktadır: shopify theme check ./sections/header.liquid geçersiz sözdizimi olup CLI bu dosyayı lint yapmayacaktır. --path bayrağı, aracın ortaya koyduğu tek ve yalnız dizin kapsamlandırma mekanizmasıdır.

Temel çıkarımlar

• --path çalıştırmayı bir dizine kapsama alır; tek bir dosya yolu kabul etmez.
• Konumsal argümanlar (ör. shopify theme check ./sections/header.liquid) desteklenmez ve yararlı bir çıktı üretmez.
• --path atlanırsa varsayılan olarak mevcut çalışma dizini kullanılır.
• SHOPIFY_FLAG_PATH ortam değişkeni, --path'in CI karşılığıdır.
• CLI 4.0'dan bu yana (Mayıs 2026'da yayınlandı), Node 22.12+ ve Git 2.28+ gereklidir.

Temel karışıklık: komut neden bir dosya kabul ediyormuş gibi görünüyor?

Diğer popüler tüm linter'lar (ESLint, Stylelint, RuboCop) konumsal dosya veya glob'u kabul eder:

eslint src/main.js          # geçerli
stylelint "src/**/*.css"    # geçerli
shopify theme check ./sections/header.liquid  # GEÇERSİZ

Shopify Theme Check bu kuralı takip etmez. CLI'nin theme check komutu hiçbir konumsal argüman kabul etmez. Bir yolu konumsal argüman olarak iletirseniz, CLI loudly hata vermez; bunun yerine bunu yok sayar ve mevcut çalışma dizinini lint yapar. Bu sessiz geri dönüş, bu hatayı bulmayı zorlaştıran şeydir.

Bu ses çıktığından daha önemlidir. Gürültülü bir dosyayı hata ayıklayan geliştirici genellikle shopify theme check ./snippets/icon-sprite.liquid çalıştırır, tam tema raporunu görür, bu dosya için kontrolün geçtiğini varsayar ve gönderir. Kontrol asla izolasyon içinde çalışmadı.

--path bayrağı: aslında ne yaptığı

--path bayrağı Theme Check'e tema kökü olarak hangi dizinin kullanılacağını söyler. Atlanırsa mevcut çalışma dizinine varsayılan olarak ayarlanır.

# Mevcut dizindeki temayı lint'le (örtülü)
shopify theme check

# Bir alt dizindeki temayı lint'le
shopify theme check --path ./my-theme

# Bir yapı çıktısı klasöründeki temayı lint'le
shopify theme check --path ./dist

Önemli: --path standart Shopify tema klasör yapısını (templates/, sections/, snippets/ vb.) içeren bir dizine işaret etmelidir. Ona tek bir dosya yolu iletmek de geçerli değildir.

Ortam değişkeni karşılığı SHOPIFY_FLAG_PATH'dir; bu, mevcut CLI'da neredeyse diğer tüm bayrakların kullandığı standart SHOPIFY_FLAG_* adlandırma desenini takip eder.

shopify theme check için tam bayraks referansı

Aslında kullanacağınız tüm bayraklar ve amaçları şunlardır:

--fail-level bayrağı CI hattı için özellikle önemlidir. Varsayılan olarak, Theme Check yalnızca error şiddetli sorunlarda kod 1 ile çıkar. Uyarılar üzerinde de bloke etmek istiyorsanız, açık olmalısınız:

shopify theme check --path ./theme --fail-level warning

CLI ile neden tek bir dosya lint'leyemezsiniz

Theme Check, bir dosya linter'ı değil, bir bütün tema linter'ı olarak tasarlanmıştır. Birçok kontrol, dosyalar arası bağlama bağlıdır:

• UnusedSnippet'in {% render %} çağıran her dosyayı bilmesi gerekir.
• TranslationKeyExists'in Liquid'iniz yanında yerel dosyaları okuması gerekir.
• MissingTemplate'in referansları kontrol etmek için tam templates/ dizinine ihtiyacı vardır.

Tek dosya kontrolü çalıştırmak, bu dosyalar arası kurallar için anlamsız sonuçlar üretirdi. Bu kasıtlı bir tasarım kararıdır, bir gözden kaçış değildir. Yazarken dosya başına geri bildirim istiyorsanız, Shopify Liquid VS Code uzantısını kullanın; bu, Theme Check'in Language Server Protocol (LSP) sunucusunu gerçek zamanlı olarak çalıştırır.

Bu, Theme Check 2.0 yayınlandığında önemli bir ilerleme oldu; linter'ı birleştirerek ve ayarlar, çeviriler, HTML ve Liquid için doğrudan editörlerde hover doklari ve kod tamamlama gibi LSP özelliklerini ekledi.

CLI 4.0'da neler değişti (Mayıs 2026)

Eski öğreticileri çalıştırıyorsanız, Mayıs 2026'da yayınlanan Shopify CLI 4.0'ın theme check'in nasıl çalıştığını etkileyen birkaç değişiklik yaptığının farkında olun:

• Varsayılan olarak otomatik yükseltme: CLI artık paket yöneticiniz aracılığıyla kendi kendini yükseltir. Otomatik yükseltme, CI ortamlarında ve ana sürüm tamamlamalarında atlanır.
• Node 22.12+ ve Git 2.28+ gereklidir. Önceki Node sürümleri kuruluşta hata verecektir.
• theme init artık Skeleton'u kopyalar, Dawn'u değil. Bu, yeni yapılar için hangi tema yapısının başlatıldığını etkiler.
• Etkileşimli oturum açma komutu yok: Mevcut CLI'da shopify login veya shopify whoami yok. Kimlik doğrulama token tabanlıdır.

CI/CD hattı için, belgelenen etkileşimsiz desen hâlâ bir linter geçidi ve bir push'tır:

shopify theme check --path ./theme --fail-level error
shopify theme push --json --theme staging

CI'da Theme Check'i kapsamlandırma: doğru yol

İşte en az ancak üretime hazır bir GitHub Actions adımı:

name: Theme Check
on: [push, pull_request]
jobs:
  theme-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Install Shopify CLI
        run: npm install -g @shopify/cli @shopify/theme
      - name: Run Theme Check
        run: shopify theme check --path . --fail-level warning
        env:
          SHOPIFY_FLAG_STORE: ${{ secrets.SHOPIFY_STORE }}

Shopify'ın resmi theme-check-action@v2'sini kullanırsanız, yol karşılığı konumsal argüman değil theme_root girdisidir:

- uses: Shopify/theme-check-action@v2
  with:
    theme_root: './dist'
    flags: '--fail-level warning'

theme_root girdisi dahili olarak --path'e eşlenir. flags girdisi, --fail-level de dahil olmak üzere herhangi bir ek bayrak iletmenizi sağlar.

Üç yaklaşım karşılaştırılması

Kontrollerin tamamını devre dışı bırakmadan yanlış pozitif sonuçları susturmak

Theme Check geçerli kodu işaretlerse (özel Liquid filtresi, üçüncü taraf etiketi), tüm kontrolü genel olarak devre dışı bırakmak yerine satır içi bastırma yorumlarını kullanın:

{% # theme-check-disable LiquidTag %}
{{ product.title | my_custom_filter }}
{% # theme-check-enable LiquidTag %}

Birden çok dosya arasında kalıcı yanlış pozitif sonuçlar için, .theme-check.yml'deki ignore anahtarı daha temizdir:

LiquidTag:
  enabled: true
  ignore:
    - snippets/vendor-component.liquid

İstediğiniz zaman shopify theme check --init komutunu çalıştırarak başlatıcı bir config oluşturabilirsiniz; bu, .theme-check.yml dosyasını Shopify'ın önerilen ayarlarıyla önceden yüklenerek yazar.

Ortam değişkeni öncelik zincirleme

Mevcut CLI'da öncelik şudur: bayrak > ortam değişkeni > shopify.theme.toml. Komut satırındaki --path bayrağı ortamdaki SHOPIFY_FLAG_PATH'i geçersiz kılar; bu da toml dosyasında ayarlanan herhangi bir yolu geçersiz kılar. Bir betikte saçılan satır içi bayrak, CI ortam değişkenini sessizce geçersiz kılır; bu, "yerel olarak çalışır ama CI'da değil" karışıklığının yaygın bir kaynağıdır.

CI adımınız hâlâ etkileşimli olarak istemde bulunuyorsa, onay istemlerini bastırmak için SHOPIFY_FLAG_FORCE=1 ekleyin.

Profesyonel bir tema geliştirme iş akışının nasıl bir araya geldiğine daha derinlemesine bakmak için, Shopify tema geliştirme Liquid en iyi uygulamalarıyla ilgili kılavuzuma bakın. Temanızın ön uç performansını lint işlemiyle birlikte optimize ediyorsanız, Shopify hız optimizasyonu tamamlayıcı çalışma zamanı tarafını kapsar.