shopify theme check --path vs Argomenti posizionali: la guida definitiva alla sintassi

Usa shopify theme check --path ./your-theme per eseguire un lint mirato a una directory. Non ci sono argomenti posizionali nella versione attuale di Shopify CLI: shopify theme check ./sections/header.liquid è una sintassi non valida e la CLI non farà il lint di quel file. Il flag --path è l'unico meccanismo che lo strumento mette a disposizione per il scoping della directory.

Punti chiave

• --path limita l'esecuzione a una directory; non accetta il percorso di un singolo file.
• Gli argomenti posizionali (ad esempio shopify theme check ./sections/header.liquid) non sono supportati e non producono output utile.
• Omettendo --path il valore predefinito è la directory di lavoro corrente.
• La variabile di ambiente SHOPIFY_FLAG_PATH è l'equivalente CI di --path.
• A partire da CLI 4.0 (rilasciata a maggio 2026), sono necessari Node 22.12+ e Git 2.28+.

La confusione di base: perché il comando sembra accettare un file

Tutti gli altri linter popolari (ESLint, Stylelint, RuboCop) accettano un file posizionale o un glob:

eslint src/main.js          # valido
stylelint "src/**/*.css"    # valido
shopify theme check ./sections/header.liquid  # NON VALIDO

Shopify Theme Check non segue questa convenzione. Il comando theme check della CLI non accetta alcun argomento posizionale. Se passi un percorso come argomento posizionale, la CLI non genera un errore evidente, ma lo ignora semplicemente e esegue il lint della directory di lavoro corrente invece. Questo fallback silenzioso è ciò che rende difficile trovare questo bug.

Questo ha più importanza di quanto possa sembrare. Gli sviluppatori che effettuano il debug di un singolo file rumoroso spesso eseguono shopify theme check ./snippets/icon-sprite.liquid, vedono un report completo del tema, presuppongono che il check sia passato per quel file e lo spediscono. Il check non è mai stato eseguito in isolamento.

Il flag --path: cosa fa realmente

Il flag --path dice a Theme Check quale directory usare come root del tema. Di default viene utilizzata la directory di lavoro corrente quando omesso.

# Lint del tema nella directory corrente (implicito)
shopify theme check

# Lint di un tema in una sottodirectory
shopify theme check --path ./my-theme

# Lint di un tema in una cartella di output build
shopify theme check --path ./dist

Importante: --path deve puntare a una directory che contiene la struttura standard della cartella del tema Shopify (templates/, sections/, snippets/, ecc.). Passare il percorso di un singolo file non è valido neanche.

L'equivalente della variabile di ambiente è SHOPIFY_FLAG_PATH, che segue il pattern di naming standard SHOPIFY_FLAG_* che quasi tutti gli altri flag utilizzano nella CLI attuale.

Riferimento completo dei flag per shopify theme check

Ecco tutti i flag che effettivamente utilizzerai, con i loro scopi:

Il flag --fail-level è particolarmente importante per le pipeline CI. Per impostazione predefinita, Theme Check esce con il codice 1 solo su problemi di gravità error. Se vuoi bloccare anche gli avvisi, devi essere esplicito:

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

Perché non puoi fare il lint di un singolo file con la CLI

Theme Check è progettato come un linter per intero tema, non un linter per singoli file. Molti check dipendono dal contesto tra file:

• UnusedSnippet ha bisogno di conoscere ogni file che chiama {% render %}.
• TranslationKeyExists ha bisogno di leggere i file di locale insieme al tuo Liquid.
• MissingTemplate ha bisogno dell'intera directory templates/ per verificare i riferimenti.

L'esecuzione di un check su un singolo file produrrebbe risultati privi di significato per quelle regole tra file. Questa è una scelta di progettazione deliberata, non un'inadvertenza. Se vuoi feedback per file mentre digiti, usa l'estensione Shopify Liquid per VS Code, che esegue il Language Server Protocol (LSP) di Theme Check in tempo reale.

Questo è stato un salto significativo in avanti quando è stato rilasciato Theme Check 2.0, unificando il linter e aggiungendo funzionalità LSP come documenti al passaggio del mouse e completamento del codice per impostazioni, traduzioni, HTML e Liquid direttamente negli editor.

Cosa è cambiato in CLI 4.0 (maggio 2026)

Se stai seguendo tutorial più vecchi, tieni presente che Shopify CLI 4.0, rilasciata a maggio 2026, ha introdotto diversi cambiamenti che interessano il modo in cui viene eseguito theme check:

• Auto-upgrade per impostazione predefinita: La CLI ora si auto-aggiorna tramite il tuo package manager. L'auto-upgrade viene saltato negli ambienti CI e sui bump della versione principale.
• Node 22.12+ e Git 2.28+ richiesti. Le versioni precedenti di Node genereranno errori durante l'installazione.
• theme init ora clona Skeleton, non Dawn. Questo influisce sulla struttura del tema sottoposta a scaffolding per i nuovi build.
• Nessun comando di login interattivo: Non esiste shopify login o shopify whoami nella CLI attuale. L'autenticazione è basata su token.

Per le pipeline CI/CD, il pattern documentato non interattivo è ancora un gate linter seguito da un push:

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

Scoping Theme Check in CI: il modo corretto

Ecco uno step GitHub Actions minimalista ma pronto per la produzione:

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

Se usi l'azione ufficiale di Shopify theme-check-action@v2, l'equivalente del path è l'input theme_root, non un argomento posizionale:

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

L'input theme_root mappa internamente a --path. L'input flags ti permette di passare qualsiasi flag aggiuntivo, incluso --fail-level.

Tre approcci a confronto

Silenziare i falsi positivi senza disabilitare interi check

Se Theme Check contrassegna il codice valido (un filtro Liquid personalizzato, un tag di terze parti), usa i commenti di soppressione inline piuttosto che disabilitare il check globalmente:

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

Per i falsi positivi persistenti su più file, la chiave ignore in .theme-check.yml è più pulita:

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

Puoi generare una configurazione iniziale in qualsiasi momento con shopify theme check --init, che scrive un file .theme-check.yml precaricato con le impostazioni consigliate di Shopify.

La catena di precedenza delle variabili di ambiente

La precedenza nella CLI attuale è: flag > variabile di ambiente > shopify.theme.toml. Un flag --path sulla riga di comando ha la precedenza su SHOPIFY_FLAG_PATH nell'ambiente, che ha la precedenza su qualsiasi path impostato nel file toml. Un flag inline casuale in uno script avrà silenziosamente la precedenza su una variabile di ambiente CI, il che è una fonte comune di confusione "funziona in locale ma non in CI".

Se il tuo step CI sta ancora invitando in modo interattivo, aggiungi SHOPIFY_FLAG_FORCE=1 per sopprimere i prompt di conferma.

Per uno sguardo più approfondito su come un flusso di lavoro professionale di sviluppo di temi si integra, consulta la mia guida sulle migliori pratiche di Liquid per lo sviluppo di temi Shopify. Se stai ottimizzando le prestazioni del front-end del tuo tema insieme al linting, l'ottimizzazione della velocità di Shopify copre il lato complementare del runtime.