Shopify Theme Check: Wie man spezifische Dateipfade und Sections Liquid-Dateien gezielt prüft

Shopify Theme Check akzeptiert keinen einzelnen Dateipfad als positionelles Argument. Das Ausführen von shopify theme check sections/hero.liquid wird nicht nur diese Datei prüfen. Das Tool validiert immer den kompletten Theme-Tree, aber mehrere unterstützte Techniken ermöglichen es dir, einzugrenzen, was geprüft wird, was mit einem Fehler beendet wird und was in deiner Ausgabe erscheint. Hier sind alle Methoden, die funktionieren, inklusive der Änderungen in Theme Check 2.x.

Wichtigste Erkenntnisse

• shopify theme check sections/hero.liquid ist ungültige Syntax und führt in Theme Check 2.x zu einem Fehler.
• --path beschränkt den Lauf auf ein Unterverzeichnis, nicht auf eine einzelne Datei.
• JSON-Ausgabe (-o json) über jq geleitet ist die einzige zuverlässige Methode, um Ergebnisse auf eine bestimmte Datei zu filtern.
• .theme-check.yml kann ganze Glob-Muster ignorieren und Rauschen von Drittanbieter- oder generierten Dateien unterdrücken.
• Inline {% # theme-check-disable CheckName %} Kommentare unterdrücken spezifische Regeln in jeder Liquid-Datei.
• Seit CLI 4.0 (Mai 2026) benötigt Theme Check Node 22.12+ und das Tool wird sich selbst über deinen Package Manager aktualisieren.

Warum es kein Single-File-Argument gibt

Theme Check ist ein Theme-übergreifender Linter, kein dateiweiser Syntax-Checker. Viele seiner Regeln sind absichtlich dateiübergreifend: MissingSnippet überprüft, ob ein {% render %} Aufruf zu einer echten Datei im Theme führt, und UnusedAssign muss jedes Template sehen, das eine Variable nutzen könnte. Das Ausführen gegen eine einzelne Datei würde bei genau diesen Checks falsch positive Ergebnisse liefern.

Deshalb bestätigt Shopifys offizielle CLI-Dokumentation, dass Theme Check zum Analysieren des kompletten Theme-Trees gedacht ist. Es gibt kein --file oder --only Flag in der aktuellen CLI.

Methode 1: --path um ein Unterverzeichnis einzugrenzen

Die nächste unterstützte Annäherung an Single-File-Linting ist --path. Es teilt Theme Check mit, wo der Theme-Root lebt, nicht welche Datei geprüft werden soll. Aber du kannst es während CI mit einer kreativen Verzeichnisstruktur kombinieren, um nah heranzukommen:

# Prüfe das komplette Theme aus dem aktuellen Arbeitsverzeichnis (Standard)
shopify theme check

# Prüfe ein Theme, das sich in einem Unterverzeichnis befindet
shopify theme check --path ./my-theme

Wenn nur dein Sections-Ordner in einem gegebenen PR verändert wurde, kannst du --path auf eine temporäre Kopie verweisen, die nur die geänderten Dateien enthält. Das ist für die meisten Teams übertrieben, aber es ist nützlich, wenn ein Monorepo mehrere Themes enthält.

Was --path NICHT macht: Es akzeptiert keine einzelne Datei wie sections/hero.liquid als Wert. Übergib ein Verzeichnis, keine Dateipfad.

Methode 2: JSON-Ausgabe zu jq geleitet zur dateiweisen Filterung

Dies ist die praktischste Methode, um eine bestimmte sections/*.liquid Datei in einer CI-Pipeline anzuzielen. Das -o json Flag von Theme Check gibt ein maschinenlesbares flaches Array, das nach Dateipfad verschlüsselt ist, aus. Leite das durch jq, um nur den Eintrag zu extrahieren, der dich interessiert:

# Führe die komplette Prüfung aus, gib JSON aus, dann filtere nach einer Datei
shopify theme check -o json \
  | jq '.[] | select(.path == "sections/hero.liquid")'

Du kannst auch selbst einen Exit-Code ungleich Null basierend auf dem gefilterten Ergebnis durchsetzen:

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 hat $ERRORS Fehler"
  exit 1
fi

Dieses Muster gibt dir das Äquivalent von dateiweiser Gating in deinem GitHub Actions oder GitLab CI Job, ohne ein Flag zu benötigen, das nicht existiert.

Methode 3: .theme-check.yml Ignore-Muster

Wenn das Ziel darin besteht, eine bestimmte Datei oder einen Ordner zu stummschalten statt ihn anzuzielen, unterstützt .theme-check.yml Glob-basierte Ignore-Listen pro Prüfung. Du kannst auch ganze Verzeichnisse von allen Prüfungen ignorieren, indem du den Top-Level ignore Schlüssel nutzt:

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

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

Generiere eine Starter-Konfiguration mit:

shopify theme check --init

Dies ist besonders nützlich, wenn du generierte oder Drittanbieter-Dateien hast (wie Replo Snippets), die absichtlich geteiltes Liquid enthalten, das sonst LiquidHTMLParsingError bei theme dev auslösen würde.

Methode 4: Inline-Suppressionskommentare in Sections Liquid

Für einmalige Regeln innerhalb einer bestimmten Section-Datei können Liquid Inline-Kommentare jedes benannte Check um einen Code-Block deaktivieren und wieder aktivieren:

{%- comment -%} Unterdrücke falsch-positives Ergebnis vom Vendor Render-Muster {%- endcomment -%}
{% # theme-check-disable UnusedAssign %}
{%- assign hero_context = section.settings.context -%}
{% # theme-check-enable UnusedAssign %}

Du kannst auch eine Prüfung für die komplette Datei unterdrücken, indem du den Disable-Kommentar in die erste Zeile platzierst:

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

Dieser Ansatz ist im Code Review sichtbar (er erscheint als einzeiliger Diff) und beeinflusst keine andere Datei im Theme.

Methode 5: VS Code onlySingleFileChecks für die lokale Entwicklung

Wenn dein Ziel schnelles Feedback in deinem Editor ist, während du aktiv eine Section-Datei bearbeitest, hat die Shopify Liquid VS Code Extension eine Einstellung, die Theme Check auf nur die offene Datei beschränkt:

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

Mit dieser Einstellung werden dateiübergreifende Prüfungen (wie MissingSnippet) übersprungen und nur Single-File-Regeln werden auf dem aktiven Tab ausgeführt. Das offizielle Repo beschreibt es als "großartig für Performance, wenn du Prüfungen ignorieren kannst, die während der Entwicklung mehrere Dateien umfassen." Führe die komplette shopify theme check in CI aus, um dateiübergreifende Probleme zu finden.

Vergleich: jede Methode nebeneinander

CLI 4.0 Anforderungen, die du nicht übersehen darfst (Mai 2026)

Seit CLI 4.0 in Mai 2026 veröffentlicht wurde, haben sich zwei Anforderungen geändert, die jede CI-Pipeline beeinflussen, die Theme Check ausführt:

• Node 22.12+ ist erforderlich. Ältere Node-Versionen werden stumm fehlschlagen oder unerwartet Ausgaben produzieren.
• Das Tool wird sich selbst über deinen Package Manager aktualisieren und überspringt Auto-Upgrade in CI absichtlich. Anheften deine Version in package.json oder deinem CI-Image explizit.

Auch wissenswert: --category und --exclude-category wurden entfernt in Theme Check 2.x (Januar 2024). Wenn du ältere Tutorials findest, die diese Flags zeigen, funktionieren sie nicht mehr. Nutze -C theme-check:all, um jede verfügbare Prüfung explizit auszuführen.

CI Gate Pattern: die richtige Methode, um Theme Check in einer Pipeline auszuführen

Hier ist die idiomatische Pipeline-Sequenz, die von Shopifys eigener Dokumentation empfohlen wird:

# 1. Gate bei Fehlern (und Warnungen, die die meisten Teams standardmaßig ignorieren)
shopify theme check --fail-level warning

# 2. Pushe zu einem unveröffentlichten Development-Theme für Vorschau
shopify theme push --unpublished --json

# 3. Befördere nur nach manueller Überprüfung
shopify theme publish --theme <ID> --force

Zwei häufige Fehler, die du vermeiden solltest:

• Das Standard --fail-level ist error, was bedeutet, dass sich Warnungen stillschweigend ansammeln und dein CI Job dennoch mit 0 beendet wird. Übergib --fail-level warning um bei ihnen zu blockieren.
• --strict bei theme push blockiert auch den Push, wenn Theme Check nicht erfolgreich ist, was dir ein zweites Sicherheitsnetz zur Deploy-Zeit gibt.

Für Per-PR Preview-Themes verbinde shopify theme push --development-context "pr-482" ein Development-Theme an einen stabilen Bezeichner wie eine PR-Nummer.

Alles zusammenbringen: der praktische Workflow für Sections Liquid

Hier ist die Sequenz, auf der die meisten Teams landen, nachdem sie das obige durchgearbeitet haben:

1. Editor: aktiviere onlySingleFileChecks in VS Code für schnelles, dateiinternes Feedback beim Schreiben von Section Liquid.
2. Pre-Commit-Hook: führe shopify theme check --fail-level error gegen das komplette Theme aus, bevor ein Commit hochgeladen wird.
3. CI Pull Request Gate: führe shopify theme check -o json | jq aus um nur die geänderten Section-Dateien zu extrahieren und zu bestätigen.
4. CI Deploy Gate: führe shopify theme push --strict aus, sodass selbst wenn jemand Schritt 3 umgeht, ein Push mit Fehlern blockiert wird.
5. Config: führe eine .theme-check.yml mit gezielten Ignore-Globs für alle generierten oder Vendor-Snippets, um falsch-positive Ergebnisse zu verhindern, die echte Arbeit blockieren.

Brauchst du Hilfe, das in eine echte Pipeline zu wiring? Die Shopify Theme Developer Service-Seite hat Kontext darüber, wie ich das für Client-Projekte einrichte, und Shopify Speed Optimization behandelt die Performance-Prüfungen, die Theme Check am häufigsten kennzeichnet.