Shopify Theme Check: Warum ein einzelnes Datei-Pfad-Argument nicht funktioniert (und was du stattdessen tun solltest)

Das Ausführen von shopify theme check ./sections/header.liquid funktioniert nicht sinnvoll. Der Befehl ist syntaktisch ungültig in der aktuellen CLI: Theme Check akzeptiert kein Positional-Datei-Pfad-Argument. Das richtige Scope-Flag ist --path, und es akzeptiert nur ein Verzeichnis, keine einzelne Datei. Hier erfährst du genau, was funktioniert, warum Single-File-Linting anders funktioniert als erwartet, und wie du es korrekt in CI integrierst.

Die wichtigsten Erkenntnisse

• shopify theme check ./sections/header.liquid ist ungültig in der aktuellen Shopify CLI. Es gibt keine Positional-Datei-Argumente.
• Verwende --path, um auf ein Verzeichnis zu verweisen (wird standardmäßig auf das aktuelle Arbeitsverzeichnis gesetzt, wenn nicht angegeben).
• Echtes Single-File-Feedback kommt vom VS Code Language Server (themeCheck.onlySingleFileChecks), nicht von der CLI.
• Der Standard---fail-level ist error, daher läuft CI stillschweigend durch, während sich Warnungen ansammeln. Gib immer --fail-level warning an.
• Seit Shopify CLI 4.0 (Mai 2026) benötigt das Tool Node 22.12+ und aktualisiert sich automatisch durch deinen Package Manager außerhalb von CI.

Der genaue Fehler, den die meisten Entwickler machen

Du bearbeitest sections/hero.liquid, entdeckst ein potenzielles Lint-Problem und gibst ein:

shopify theme check ./sections/hero.liquid

Nichts Sinnvolles geschieht. In der aktuellen CLI wird dieses Positional-Argument einfach ignoriert oder erzeugt einen Fehler über ein fehlendes Theme-Verzeichnis.

Diese Verwechslung hat eine spezifische Ursache: Theme Check 2.x (die in Shopify CLI mitgelieferte Node-basierte Version) hat das ältere Ruby-Gem ersetzt, und das Ruby-Gem akzeptierte tatsächlich ein Pfad-Positional-Argument. Ältere Tutorials, StackOverflow-Antworten und Blog-Posts, die vor der Theme-Check-2.x-Migration geschrieben wurden (abgeschlossen Anfang 2024, wobei --category und --exclude-category zur gleichen Zeit entfernt wurden), zeigen immer noch die alte Syntax. Diese Posts sind heute falsch.

Wie in Shopifys eigenem CLI-Referenz bestätigt wird, ist --path die einzige Möglichkeit, einen Durchlauf zu begrenzen, und es begrenzt auf ein Verzeichnis, nicht auf eine Datei.

Was das Flag tatsächlich tut

# Auf ein spezifisches Theme-Verzeichnis begrenzen
shopify theme check --path ./my-theme

# Standardmäßig auf das aktuelle Arbeitsverzeichnis
shopify theme check

# Behebbare Verstöße automatisch korrigieren
shopify theme check -a

# Ändere, welche Schweregrad-Stufe zu einem Exit-Code ungleich Null führt
shopify theme check --fail-level warning

# Maschinenlesbarer Output (flaches Array pro Datei)
shopify theme check -o json > results.json

# Liste jeden aktiven Check und seine Schweregrad auf
shopify theme check --list

--path sagt Theme Check, welches Verzeichnis als Theme-Root behandelt werden soll. Jede Datei in diesem Verzeichnis (Templates, Sections, Snippets, Layout, Assets) wird in einem Durchlauf überprüft. Du kannst es auf CLI-Ebene nicht auf eine einzelne Datei begrenzen.

Wie du eine einzelne Datei wirklich lintest: der Language-Server-Ansatz

Die CLI ist ein Whole-Theme-Tool. Single-File-Feedback ist die Aufgabe des Shopify Liquid Language Server, der die Shopify Liquid VS Code Extension antreibt.

Die Extension stellt eine Einstellung namens themeCheck.onlySingleFileChecks bereit. Wenn diese auf true gesetzt wird, deaktiviert sie Whole-Theme-Checks (wie UnusedSnippet und TranslationKeyExists) und überprüft nur die Dateien, die gerade im Editor geöffnet sind. Dies lässt textDocument/didChange-Checks etwa 125x schneller laufen als vollständige Theme-Re-Checks bei jedem Tastendruck.

Füge dies zu deinen VS Code Workspace-Einstellungen hinzu:

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

Der Kompromiss: Du wirst Cross-File-Checks während der Kodierung vermissen. Das empfohlene Muster ist, onlySingleFileChecks: true lokal zur Geschwindigkeitssteigerung zu verwenden, dann das vollständige shopify theme check auf das gesamte Theme in CI vor jedem Push auszuführen.

Vergleich: CLI vs. Language Server für Single-File-Feedback

Die --fail-level Falle, die CI stillschweigend bricht

Dies verwirrt fast jedes Team, das zum ersten Mal ein Lint-Gate einrichtet.

Standardmäßig ist --fail-level auf error eingestellt. Das bedeutet, dass ein Durchlauf, der nur Warnungen findet, mit dem Code 0 endet. Dein CI-Job prüft den Exit-Code, sieht 0, markiert den Schritt grün, und diese Warnungen sammeln sich stillschweigend über Dutzende von PRs an, bis jemand schließlich bemerkt, dass ein veralteter Filter oder ein Performance-Problem, das monatelang in der Produktion sitzt, da ist.

Behebe es in einer Zeile:

shopify theme check --fail-level warning

Akzeptierte Level, von strikt zu weniger strikt:

• info
• suggestion
• style
• warning
• error (Standard)
• crash

Für die meisten Shops ist warning die richtige Schwelle. Es findet echte Probleme, ohne auf rein stilistische Vorschläge zu stoßen.

Ein produktionsgerechtes CI-Muster (GitHub Actions)

Nachfolgend ist das minimale, aktuelle Muster. Es verwendet SHOPIFY_CLI_THEME_TOKEN für nicht-interaktive Authentifizierung und begrenzt den Build auf Theme Check vor jedem Push.

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 }}

Beachte, dass --strict auf theme push nur bei Theme-Check-Fehlern blockiert, daher ist das Übergeben von --fail-level warning im dedizierten Check-Schritt das richtige Gate, anstatt sich nur auf --strict zu verlassen.

Drei weitere Flags, die es zu kennen lohnt

• -a / --auto-correct: behebt Verstöße, die Theme Check ohne menschliches Urteil lösen kann (Abstände in {% %}, ungenutzte Zuweisungen). Führe dies lokal aus, niemals blind in CI.
• --list: gibt jeden aktivierten Check und seine Schweregrad aus. Nützlich, wenn ein Teamkollege eine .theme-check.yml hinzufügt und du die aktive Regelmenge vor einer Veröffentlichung überprüfen möchtest.
• -C theme-check:all: aktiviert jeden verfügbaren Check, auch solche, die in theme-check:recommended deaktiviert sind. Verwende dies für eine periodische umfassende Prüfung, nicht als tägliches Gate.

Was sich in CLI 4.0 (Mai 2026) geändert hat, was dein Setup betrifft

Wenn deine Pipeline nach Mai 2026 merkwürdig zu verhalten begann, ist die Ursache wahrscheinlich Shopify CLI 4.0. Zwei Dinge haben sich geändert, die Theme-Check-Läufe beeinflussen:

1. Node 22.12+ ist jetzt erforderlich. Pipelines, die auf Node 18 oder 20 festgelegt sind, werden beim Install-Schritt fehlschlagen.
2. Auto-Upgrade wird in CI übersprungen. Die CLI erkennt CI-Umgebungen und aktualisiert sich nicht selbst, was das richtige Verhalten ist. Aber lokale Projekt-Installs überspringen auch das Auto-Upgrade, daher stelle sicher, dass deine Pipeline explizit die Version installiert, die du möchtest.

Bonus: theme init klont jetzt standardmäßig Shopifys Skeleton-Theme anstelle von Dawn. Das beeinflusst Theme-Check-Verhalten nicht, ist aber wichtig, wenn du in derselben Pipeline ein neues Projekt gerüst aufbaust.

Häufige .theme-check.yml Fehler

Deine .theme-check.yml Datei sitzt am Theme-Root und kontrolliert, welche Checks laufen und mit welcher Schweregrad. Ein paar Muster, die Verwirrung verursachen:

# Richtig: von empfohlen erweitern, dann überschreiben
extend: theme-check:recommended

TemplateLength:
  enabled: false

UnusedAssign:
  severity: suggestion   # downgrade from warning

ParserBlockingJavaScript:
  enabled: true
  severity: error

• Verwende nicht --category oder --exclude-category. Diese Flags wurden in Theme Check 2.x entfernt. Verwende stattdessen die YAML-Datei.
• Der root-Schlüssel wird nur benötigt, wenn deine Theme-Dateien in einem Unterverzeichnis leben (z.B. ein Build-Output-Ordner wie dist/). Du brauchst ihn nicht für eine Standard-Dawn- oder Horizon-Struktur.

Für einen breiteren Überblick darüber, wie Theme Check in einen vollständigen Shopify-Theme-Workflow passt, siehe meinen Leitfaden zu Shopify Theme-Entwicklung und Liquid Best Practices.

Wenn du dies in eine CI/CD-Pipeline als Teil einer größeren Migration oder eines Build-Systems integrierst, behandelt die Shopify Theme-Developer-Seite wie wir automatisierte Qualitätsgates bei Client-Projekten angehen.