Shopify Theme Check: Neden Tek Dosya Yolu Argümanı Çalışmıyor (ve Bunun Yerine Ne Yapmalı)

shopify theme check ./sections/header.liquid komutunu çalıştırmak yararlı bir sonuç vermez. Bu komut sözdizimi mevcut CLI'de geçersizdir: Theme Check konumsal dosya yolu argümanını kabul etmez. Doğru kapsam bayrağı --path olup, bu yalnızca bir dizini kabul eder, tek bir dosyayı değil. İşte tam olarak neyin çalıştığı, neden tek dosya linting'i beklediğinizden farklı çalıştığı ve bunu CI'ye nasıl entegre edeceğiniz.

Ana çıkarımlar

• shopify theme check ./sections/header.liquid mevcut Shopify CLI'de geçersizdir. Konumsal dosya argümanları yoktur.
• Bir dizine işaret etmek için --path kullanın (atlanırsa mevcut çalışma dizinine varsayılan olur).
• Gerçek tek dosya geribildirim VS Code Dil Sunucusundan gelir (themeCheck.onlySingleFileChecks), CLI'den değil.
• Varsayılan --fail-level error olup, bu sebeple CI uyarılar birikmeye devam ederken sessizce geçer. Her zaman --fail-level warning iletin.
• Shopify CLI 4.0 (Mayıs 2026) itibarıyla, araç Node 22.12+ gerektirmektedir ve CI dışında paket yöneticiniz aracılığıyla otomatik güncellenir.

Çoğu geliştiricinin yaptığı tam hata

sections/hero.liquid dosyasını düzenliyor, potansiyel bir lint sorunu fark ediyor ve şunu yazıyorsunuz:

shopify theme check ./sections/hero.liquid

Yararlı bir şey olmaz. Mevcut CLI'de, bu konumsal argüman basitçe yok sayılır veya eksik tema dizini hakkında bir hata üretir.

Bu karışıklığın belirli bir nedeni vardır: Theme Check 2.x (Shopify CLI'nin içinde gelen Node tabanlı sürüm), eski Ruby gem'ini değiştirmiştir ve Ruby gem'i gerçekten bir yol konumsal argümanı kabul ediyordu. Theme Check 2.x göçünden önce yazılmış eski öğreticiler, StackOverflow cevapları ve blog yazıları (2024 başında tamamlandı, aynı zamanda --category ve --exclude-category kaldırıldı) hala eski söz dizimini göstermektedir. Bu yazılar şimdi yanlıştır.

Shopify'nin kendi CLI referansında onaylandığı gibi, --path bir çalıştırmayı kapsamanın tek yoludur ve bu, bir dizine kapsamlanır, dosyaya değil.

Bayrağın aslında ne yaptığı

# Belirli bir tema dizinine kapsamlandır
shopify theme check --path ./my-theme

# Mevcut çalışma dizinine varsayılan olur
shopify theme check

# Düzeltilebilir ihlalleri yerinde otomatik düzelt
shopify theme check -a

# Sıfır olmayan çıkışa neden olan önem seviyesini değiştir
shopify theme check --fail-level warning

# Makine tarafından okunabilir çıktı (dosya başına düz dizi)
shopify theme check -o json > results.json

# Etkin her kontrolü ve önem seviyesini listele
shopify theme check --list

--path, Theme Check'e tema kökü olarak hangi dizini kullanacağını söyler. O dizinin içindeki her dosya (templates, sections, snippets, layout, assets) tek bir geçişte kontrol edilir. CLI düzeyinde bunu tek bir dosyaya daraltamazsınız.

Tek bir dosyayı gerçekte linting nasıl yapılır: Dil Sunucusu yaklaşımı

CLI bir bütün tema aracıdır. Tek dosya geribildirim, Shopify Liquid VS Code uzantısını güçlendiren Shopify Liquid Dil Sunucusu'nun işidir.

Uzantı themeCheck.onlySingleFileChecks adında bir ayar gösterir. true olarak ayarlandığında, bütün tema kontrolleri (örneğin UnusedSnippet ve TranslationKeyExists) devre dışı bırakılır ve yalnızca editörde açık olan dosyalar kontrol edilir. Bu, textDocument/didChange kontrolleri her tuş vuruşunda tam tema yeniden kontrolleri ile karşılaştırıldığında kabaca 125 kat daha hızlı çalışmasını sağlar.

Bunu VS Code çalışma alanı ayarlarınıza ekleyin:

{
  "themeCheck.checkOnOpen": true,
  "themeCheck.checkOnChange": true,
  "themeCheck.checkOnSave": true,
  "themeCheck.onlySingleFileChecks": true
}

Değiş tokuş: kodlamaya devam ederken dosyalar arası kontrolleri kaçıracaksınız. Önerilen desen, yerel olarak hız için onlySingleFileChecks: true çalıştırmak, sonra herhangi bir push'tan önce CI'de tam temada tam shopify theme check çalıştırmaktır.

Karşılaştırma: Tek dosya geribildirim için CLI vs Dil Sunucusu

CI'yi sessizce kıran --fail-level tuzağı

Bu, linting kapısını ilk kez kuran hemen hemen her takımı kandırır.

Varsayılan olarak, --fail-level error olarak ayarlanır. Bu, yalnızca uyarılar bulmanın bir çalıştırması 0 çıkış koduyla çıkacağı anlamına gelir. CI işiniz çıkış kodunu kontrol eder, 0 görür, adımı yeşil olarak işaretler ve bu uyarılar, birinin nihayet kullanımdan kaldırılmış bir filtre veya üretimde aylardır oturan bir performans kokusunu fark ettiği zamana kadar düzine PR'lerde sessizce birikir.

Bir satırda düzeltin:

shopify theme check --fail-level warning

Kabul edilen seviyeler, en sıkıdan en az sıkıya doğru:

• info
• suggestion
• style
• warning
• error (varsayılan)
• crash

Çoğu mağaza için warning doğru eşiktir. Gerçek sorunları, tamamen stilistik önerilere engel olmadan yakalar.

Üretim sınıfı CI deseni (GitHub Actions)

Aşağıda minimal, mevcut desen yer almaktadır. Etkileşimsiz auth için SHOPIFY_CLI_THEME_TOKEN kullanır ve herhangi bir push'tan önce Theme Check'te yapıyı kontrol eder.

name: Theme Lint and Deploy
on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        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 -o json > tc-results.json
        env:
          SHOPIFY_FLAG_STORE: ${{ secrets.SHOPIFY_STORE }}

      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: theme-check-results
          path: tc-results.json

  deploy:
    needs: lint
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Install Shopify CLI
        run: npm install -g @shopify/cli @shopify/theme
      - name: Push theme
        run: shopify theme push --json --theme ${{ secrets.SHOPIFY_THEME_ID }}
        env:
          SHOPIFY_CLI_THEME_TOKEN: ${{ secrets.SHOPIFY_CLI_THEME_TOKEN }}
          SHOPIFY_FLAG_STORE: ${{ secrets.SHOPIFY_STORE }}

theme push üzerindeki --strict yalnızca Theme Check hatalarında engel olduğu için, --fail-level warning'i ayrılmış kontrol adımında geçmek doğru kapı olup, yalnızca --strict'e güvenmek değildir.

Bilmeye değer üç bayrak daha

• -a / --auto-correct: Theme Check'in insan yargısı olmaksızın çözebileceği ihlalleri düzeltir (boşluk {% %} içinde, kullanılmayan atamaları). Bunu yerel olarak çalıştırın, CI'de asla kör şekilde çalıştırmayın.
• --list: etkin her kontrolü ve önem seviyesini yazdırır. Takım üyesi .theme-check.yml eklediğinde ve sürüm öncesi etkin kural setini doğrulamak istediğinizde kullanışlıdır.
• -C theme-check:all: theme-check:recommended içinde devre dışı bırakılanlar da dahil olmak üzere kullanılabilir her kontrolü etkinleştirir. Bunu günlük kapı olarak değil, periyodik derin denetim için kullanın.

CLI 4.0'da (Mayıs 2026) değişen ve kurulumunuzu etkileyen neler var

Ardışık düzeni Mayıs 2026'dan sonra garip şekilde davranmaya başlarsa, nedeni muhtemelen Shopify CLI 4.0'dır. Theme check çalışmalarını etkileyen iki şey değişmiştir:

1. Node 22.12+ şimdi gereklidir. Node 18 veya 20'ye sabitlenmiş ardışık düzenler install adımında başarısız olur.
2. CI'de otomatik yükseltme atlanır. CLI, CI ortamlarını algılar ve kendi kendini güncellemez, bu doğru davranıştır. Ancak yerel proje kurulumları da otomatik yükseltmeyi atlasa, ardışık düzeni açıkça istediğiniz sürümü kuracak şekilde yapılandırdığınızdan emin olun.

Ek olarak, theme init şimdi Dawn yerine Shopify'nin Skeleton temасını varsayılan olarak klonlar. Bu Theme Check davranışını etkilemez, ancak ardışık düzende yeni bir proje iskele kuruyorsanız önemlidir.

Yaygın .theme-check.yml hataları

.theme-check.yml dosyası tema kökünde yer alır ve hangi kontrollerin çalıştığını ve hangi önemin yer aldığını denetler. Karışıklığa neden olan birkaç desen:

# Doğru: önerilenden genişlet, sonra geçersiz kıl
extend: theme-check:recommended

TemplateLength:
  enabled: false

UnusedAssign:
  severity: suggestion   # uyarıdan düşür

ParserBlockingJavaScript:
  enabled: true
  severity: error

• --category veya --exclude-category kullanmayın. Bu bayraklar Theme Check 2.x'te kaldırılmıştır. Bunun yerine YAML dosyasını kullanın.
• root anahtarı, yalnızca tema dosyalarınız bir alt dizinde yaşadığında gereklidir (örn. dist/ gibi bir yapı çıktı klasörü). Standart Dawn veya Horizon yapısı için buna ihtiyacınız yoktur.

Theme Check'in tam Shopify tema iş akışına nasıl uyduğu için daha geniş bir bakış için bkz. Shopify tema geliştirme ve Liquid en iyi uygulamaları rehberim.

Bunu daha büyük bir göç veya yapı sisteminin parçası olarak bir CI/CD ardışık düzenine entegre etiyorsanız, Shopify tema geliştirici hizmet sayfası istemci projelerinde otomatik kalite kapılarına nasıl yaklaştığımızı kapsamaktadır.