shopify theme check --path versus positionale argumenten: de definitieve syntaxgids

Gebruik shopify theme check --path ./your-theme om een lint-run tot een map in te beperken. Er zijn geen positionale argumenten in de huidige Shopify CLI: shopify theme check ./sections/header.liquid is ongeldig en de CLI zal dat bestand niet controleren. De --path vlag is het enige mechanisme dat het hulpprogramma voor mapbepaling blootstelt.

Belangrijkste conclusies

• --path beperkt de run tot een map, het accepteert GEEN enkel bestandspad.
• Positionale argumenten (bijv. shopify theme check ./sections/header.liquid) worden NIET ondersteund en produceren geen nutvolle uitvoer.
• Weglating van --path gebruikt standaard de huidige werkmap.
• De SHOPIFY_FLAG_PATH omgevingsvariabele is het CI-equivalent van --path.
• Sinds CLI 4.0 (mei 2026) zijn Node 22.12+ en Git 2.28+ vereist.

De kernverwarring: waarom het commando eruit ziet alsof het een bestand zou accepteren

Elke andere populaire linter (ESLint, Stylelint, RuboCop) accepteert een positional bestand of glob:

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

Shopify Theme Check volgt die conventie niet. Het CLI-commando theme check accepteert helemaal geen positionale argumenten. Als je een pad als positional argument doorgeeft, geeft de CLI geen sterke fout; het negeert het gewoon en controleert in plaats daarvan de huidige werkmap. Die stille terugval is wat deze bug moeilijk te vinden maakt.

Dit is belangrijker dan het klinkt. Ontwikkelaars die een enkel luidruchtig bestand debuggen, voeren vaak shopify theme check ./snippets/icon-sprite.liquid uit, zien een volledige themerapport, nemen aan dat de controle voor dat bestand is geslaagd, en publiceren. De controle werd nooit in isolatie uitgevoerd.

De --path vlag: wat het eigenlijk doet

De --path vlag vertelt Theme Check welke map als themahoofdmap moet worden gebruikt. Het staat standaard in op de huidige werkmap als het wordt weggelaten.

# Controleer het thema in de huidige map (impliciet)
shopify theme check

# Controleer een thema in een submap
shopify theme check --path ./my-theme

# Controleer een thema in een builduitvoermap
shopify theme check --path ./dist

Belangrijk: --path moet naar een map wijzen die de standaard Shopify-themafolderstructuur bevat (templates/, sections/, snippets/, enzovoort). Het doorgeven van een enkel bestandspad is ook niet geldig.

De omgevingsvariabeleequivalent is SHOPIFY_FLAG_PATH, die het standaard SHOPIFY_FLAG_* naampatroon volgt dat bijna elke andere vlag in de huidige CLI gebruikt.

Volledige vlagverwijzing voor shopify theme check

Hier zijn alle vlaggen die je daadwerkelijk zult gebruiken, met hun doeleinden:

De --fail-level vlag is vooral belangrijk voor CI-pijplijnen. Standaard sluit Theme Check alleen af met code 1 bij error ernstige problemen. Als je ook wilt blokkeren op waarschuwingen, moet je expliciet zijn:

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

Waarom je geen enkel bestand met de CLI kunt controleren

Theme Check is ontworpen als een hele-themachecker, niet een bestandschecker. Veel controles hangen af van context tussen bestanden:

• UnusedSnippet moet weten welk bestand {% render %} aanroept.
• TranslationKeyExists moet localebestanden naast je Liquid lezen.
• MissingTemplate heeft de volledige templates/ map nodig om verwijzingen te controleren.

Het uitvoeren van een check met één bestand zou zinloze resultaten opleveren voor die cross-file regels. Dit is een bewuste ontwerpkeuze, geen vergissing. Als je per-bestandsfeedback wilt terwijl je typt, gebruik je de Shopify Liquid VS Code-extensie, die Theme Check's Language Server Protocol (LSP) in real-time uitvoert.

Dit was een aanzienlijke vooruitgang toen Theme Check 2.0 werd uitgebracht, wat de linter verenigde en LSP-functies toevoegde zoals hover-documentatie en code-aanvulling voor instellingen, vertalingen, HTML en Liquid rechtstreeks in editors.

Wat is er veranderd in CLI 4.0 (mei 2026)

Als je oudere tutorials gebruikt, wees ervan bewust dat Shopify CLI 4.0, uitgebracht in mei 2026, verschillende wijzigingen introduceerde die van invloed zijn op hoe theme check wordt uitgevoerd:

• Auto-upgrade standaard: De CLI wordt nu automatisch bijgewerkt via je packagemanager. Auto-upgrade wordt overgeslagen in CI-omgevingen en bij grote versiewisselingen.
• Node 22.12+ en Git 2.28+ vereist. Eerdere Node-versies geven fouten bij installatie.
• theme init kloont nu Skeleton, niet Dawn. Dit beïnvloedt welke themastructuur voor nieuwe builds wordt gesteigerd.
• Geen interactieve inlogcommando's: Er is geen shopify login of shopify whoami op de huidige CLI. Verificatie is op tokens gebaseerd.

Voor CI/CD-pijplijnen is het gedocumenteerde non-interactieve patroon nog steeds een linter-gate gevolgd door een push:

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

Theme Check in CI bereiken: op de juiste manier

Hier is een minimale maar productie-klare GitHub Actions-stap:

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

Als je Shopify's officiële theme-check-action@v2 gebruikt, is het padequivalent de theme_root input, niet een positional argument:

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

De theme_root input wordt intern op --path afgebeeld. De flags input laat je extra vlaggen doorgeven, inclusief --fail-level.

Drie benaderingen vergeleken

Fout-positieven stilzwijgen zonder hele controles uit te schakelen

Als Theme Check geldige code markeert (een aangepast Liquid-filter, een tag van derden), gebruikt u inline onderdrukkomentaren in plaats van de hele controle globaal uit te schakelen:

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

Voor blijvende fout-positieven in meerdere bestanden is de ignore sleutel in .theme-check.yml schoner:

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

Je kunt op elk moment een starter-configuratie genereren met shopify theme check --init, die een .theme-check.yml schrijft die vooraf is geladen met Shopify's aanbevolen instellingen.

De omgevingsvariabelerangschikkingsketen

Rangschikking in de huidige CLI is: vlag > omgevingsvariabele > shopify.theme.toml. Een --path vlag op de opdrachtregel overschrijft SHOPIFY_FLAG_PATH in de omgeving, wat overschrijft een pad dat in het toml-bestand is ingesteld. Een dwaalse inline vlag in een script overschrijft geruisloos een CI-omgevingsvariabele, wat een veelvoorkomende bron van "het werkt lokaal maar niet in CI" verwarring is.

Als je CI-stap nog steeds interactief vraagt, voeg SHOPIFY_FLAG_FORCE=1 toe om bevestigingsvragen te onderdrukken.

Voor een dieper inzicht in hoe een professionele workflow voor themaontwikkeling in elkaar zit, raadpleeg je mijn gids over best practices voor Shopify-themaontwikkeling Liquid. Als je de front-endprestaties van je thema optimaliseert naast linting, Shopify-snelheidsoptimalisatie behandelt de aanvullende runtimezijde.