shopify theme check --path vs Positionsargumente: Der definitive Syntax-Guide

Verwenden Sie shopify theme check --path ./your-theme, um einen Lint-Durchlauf auf ein Verzeichnis zu beschränken. Es gibt keine Positionsargumente in der aktuellen Shopify CLI: shopify theme check ./sections/header.liquid ist ungültige Syntax und die CLI wird diese Datei nicht überprüfen. Das --path Flag ist der einzige Mechanismus, den das Tool für Verzeichnisbegrenzung bietet.

Wichtigste Erkenntnisse

• --path beschränkt den Durchlauf auf ein Verzeichnis und akzeptiert keine einzelne Dateipfade.
• Positionsargumente (z. B. shopify theme check ./sections/header.liquid) werden nicht unterstützt und erzeugen keine nützliche Ausgabe.
• Das Weglassen von --path führt zur Standardeinstellung des aktuellen Arbeitsverzeichnisses.
• Die Umgebungsvariable SHOPIFY_FLAG_PATH ist das CI-Äquivalent von --path.
• Seit CLI 4.0 (veröffentlicht Mai 2026) werden Node 22.12+ und Git 2.28+ benötigt.

Die Kernverwirrung: Warum der Befehl so aussieht, als würde er eine Datei akzeptieren

Jeder andere beliebte Linter (ESLint, Stylelint, RuboCop) akzeptiert ein Positionsargument oder einen Glob:

eslint src/main.js          # valid
stylelint "src/**/*.css"    # valid
shopify theme check ./sections/header.liquid  # INVALID

Shopify Theme Check folgt dieser Konvention nicht. Der theme check Befehl der CLI akzeptiert überhaupt keine Positionsargumente. Wenn Sie einen Pfad als Positionsargument übergeben, wird die CLI nicht laut fehlschlagen, sondern ignoriert ihn einfach und überprüft stattdessen das aktuelle Arbeitsverzeichnis. Dieses stille Fallback macht diesen Fehler schwer zu finden.

Dies ist wichtiger, als es klingt. Entwickler, die eine einzelne laute Datei debuggen, führen oft shopify theme check ./snippets/icon-sprite.liquid aus, sehen einen Bericht mit vollem Theme, nehmen an, dass die Überprüfung für diese Datei bestanden hat, und versenden. Die Überprüfung wurde nie isoliert durchgeführt.

Das --path Flag: Was es tatsächlich tut

Das --path Flag teilt Theme Check mit, welches Verzeichnis als Theme-Stamm verwendet werden soll. Es hat die Standardeinstellung des aktuellen Arbeitsverzeichnisses, wenn es weggelassen wird.

# Überprüfen Sie das Theme im aktuellen Verzeichnis (implizit)
shopify theme check

# Überprüfen Sie ein Theme in einem Unterverzeichnis
shopify theme check --path ./my-theme

# Überprüfen Sie ein Theme in einem Build-Output-Ordner
shopify theme check --path ./dist

Wichtig: --path muss auf ein Verzeichnis zeigen, das die standardmäßige Shopify Theme Ordnerstruktur (templates/, sections/, snippets/ usw.) enthält. Es ist auch nicht gültig, einen einzelnen Dateipfad zu übergeben.

Das Umgebungsvariablenenäquivalent ist SHOPIFY_FLAG_PATH, das dem standardmäßigen Benennungsmuster SHOPIFY_FLAG_* folgt, das fast alle anderen Flags in der aktuellen CLI verwenden.

Vollständige Flag-Referenz für shopify theme check

Hier sind alle Flags, die Sie tatsächlich verwenden werden, mit ihren Zwecken:

Das --fail-level Flag ist besonders wichtig für CI-Pipelines. Standardmäßig beendet Theme Check nur mit Code 1 bei error Schweregrad. Wenn Sie auch bei Warnungen blockieren möchten, müssen Sie explizit sein:

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

Warum Sie mit der CLI keine einzelne Datei überprüfen können

Theme Check ist als ein Ganz-Theme-Linter konzipiert, nicht als Datei-Linter. Viele Überprüfungen hängen von dateiübergreifendem Kontext ab:

• UnusedSnippet muss jede Datei kennen, die {% render %} aufruft.
• TranslationKeyExists muss Locale-Dateien neben Ihrem Liquid lesen.
• MissingTemplate muss das vollständige templates/ Verzeichnis überprüfen, um Referenzen zu überprüfen.

Eine Überprüfung einzelner Dateien würde für diese dateiübergreifenden Regeln bedeutungslose Ergebnisse erzeugen. Das ist eine bewusste Design-Entscheidung, kein Versehen. Wenn Sie während des Schreibens Pro-Datei-Feedback möchten, verwenden Sie die Shopify Liquid VS Code Erweiterung, die das Language Server Protocol (LSP) von Theme Check in Echtzeit ausführt.

Dies war ein großer Fortschritt, als Theme Check 2.0 veröffentlicht wurde, das den Linter vereinheitlichte und LSP-Features wie Hover-Dokumentation und Codeergänzung für Einstellungen, Übersetzungen, HTML und Liquid direkt in Editoren hinzufügte.

Was sich in CLI 4.0 geändert hat (Mai 2026)

Wenn Sie ältere Tutorials verwenden, beachten Sie, dass Shopify CLI 4.0, veröffentlicht im Mai 2026, mehrere Änderungen einführte, die beeinflussen, wie theme check ausgeführt wird:

• Auto-Upgrade standardmäßig: Die CLI führt jetzt automatische Aktualisierungen über Ihren Package Manager durch. Auto-Upgrade wird in CI-Umgebungen und bei Major-Version-Bumps übersprungen.
• Node 22.12+ und Git 2.28+ erforderlich. Frühere Node-Versionen werfen Fehler bei der Installation.
• theme init klont jetzt Skeleton, nicht Dawn. Dies beeinflusst, welche Theme-Struktur für neue Builds eingerüstet wird.
• Keine interaktiven Login-Befehle: Es gibt kein shopify login oder shopify whoami in der aktuellen CLI. Die Authentifizierung ist tokenbasiert.

Für CI/CD-Pipelines ist das dokumentierte nicht-interaktive Muster immer noch ein Linter-Gate gefolgt von einem Push:

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

Theme Check in CI begrenzen: Der richtige Weg

Hier ist ein minimaler, aber produktionsreifer GitHub Actions Schritt:

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

Wenn Sie die offizielle theme-check-action@v2 von Shopify verwenden, ist das Pfad-Äquivalent die theme_root Eingabe, nicht ein Positionsargument:

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

Die theme_root Eingabe wird intern auf --path abgebildet. Die flags Eingabe ermöglicht es Ihnen, beliebige zusätzliche Flags zu übergeben, einschließlich --fail-level.

Drei Ansätze im Vergleich

Falsche Positive stumm schalten, ohne ganze Überprüfungen zu deaktivieren

Wenn Theme Check gültigen Code kennzeichnet (einen benutzerdefinierten Liquid Filter, einen Tag von Drittanbietern), verwenden Sie stattdessen Inline-Unterdrückungskommentare, anstatt die ganze Überprüfung global zu deaktivieren:

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

Für anhaltende falsche Positive über mehrere Dateien hinweg ist der ignore Schlüssel in .theme-check.yml sauberer:

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

Sie können jederzeit eine Starter-Konfiguration mit shopify theme check --init generieren, die eine .theme-check.yml mit Shopifys empfohlenen Einstellungen schreibt.

Die Umgebungsvariablen-Präzedenzordnung

Die Präzedenzordnung in der aktuellen CLI ist: Flag > Umgebungsvariable > shopify.theme.toml. Ein --path Flag in der Befehlszeile überschreibt SHOPIFY_FLAG_PATH in der Umgebung, die alle in der Toml-Datei festgelegten Pfade überschreibt. Ein verirrtes Inline-Flag in einem Skript überschreibt stillschweigend eine CI-Umgebungsvariable, was eine häufige Quelle für "Es funktioniert lokal, aber nicht in CI" Verwirrung ist.

Wenn Ihr CI-Schritt immer noch interaktiv auffordert, fügen Sie SHOPIFY_FLAG_FORCE=1 hinzu, um Bestätigungsaufforderungen zu unterdrücken.

Für einen tieferen Blick darauf, wie ein professioneller Theme-Entwicklungs-Workflow zusammenpasst, lesen Sie meinen Guide zu Shopify Theme-Entwicklung Liquid Best Practices. Wenn Sie die Front-End-Performance Ihres Themes neben dem Linting optimieren, behandelt Shopify Speed Optimization die komplementäre Runtime-Seite.