Shopify Theme Check: Come scegliere file e sezioni specifiche con Liquid

Shopify Theme Check non accetta un singolo percorso file come argomento posizionale. Eseguire shopify theme check sections/hero.liquid non analizzerà solo quel file. Lo strumento valida sempre l'intero albero del tema, ma diversi metodi supportati ti permettono di restringere cosa viene controllato, cosa esce con un errore e cosa appare nel tuo output. Ecco ogni metodo che funziona, inclusi i cambiamenti introdotti in Theme Check 2.x.

Punti chiave

• shopify theme check sections/hero.liquid è sintassi non valida e esce con un errore in Theme Check 2.x.
• --path limita l'esecuzione a una sottodirectory, non a un singolo file.
• L'output JSON (-o json) passato attraverso jq è l'unico modo affidabile per filtrare i risultati a un file specifico.
• .theme-check.yml può ignorare interi pattern glob, silenziando il rumore dai file di terze parti o generati.
• I commenti inline {% # theme-check-disable CheckName %} sopprimono regole specifiche all'interno di qualsiasi file Liquid.
• Dall'interfaccia CLI 4.0 (maggio 2026), Theme Check richiede Node 22.12+ e lo strumento si auto-aggiorna tramite il tuo package manager.

Perché non c'è un argomento per un singolo file

Theme Check è un linter per l'intero tema, non un controllore di sintassi file per file. Molte delle sue regole sono multifile per design: MissingSnippet controlla se una chiamata {% render %} si risolve a un file reale altrove nel tema, e UnusedAssign ha bisogno di vedere ogni template che potrebbe consumare una variabile. Eseguirlo su un singolo file in isolamento produrrebbe falsi positivi esattamente su quelle verifiche.

Per questo motivo, la documentazione ufficiale CLI di Shopify conferma che Theme Check è pensato per analizzare l'intero albero del tema. Non esiste un flag --file o --only nell'interfaccia CLI attuale.

Metodo 1: --path per limitare una subdirectory

L'approssimazione più vicina al linting di un singolo file è --path. Dice a Theme Check dove risiede la radice del tema, non quale file controllare. Ma puoi combinarlo con una struttura di directory creativa durante CI per arrivare vicino:

# Analizza l'intero tema dalla directory di lavoro attuale (predefinito)
shopify theme check

# Analizza un tema che vive dentro una subdirectory
shopify theme check --path ./my-theme

Se la cartella sections è l'unica parte del repo che è stata modificata in una determinata PR, puoi puntare --path a una copia temporanea che contiene solo i file modificati. Questo è eccessivo per la maggior parte dei team, ma è utile quando un monorepo contiene più temi.

Cosa --path NON fa: non accetta un singolo file come sections/hero.liquid come suo valore. Passa una directory, non un percorso file.

Metodo 2: Output JSON passato a jq per filtraggio per file

Questo è il metodo più pratico per scegliere un file sections/*.liquid specifico in una pipeline CI. Il flag -o json di Theme Check emette un array piatto leggibile da macchina con chiave percorso file. Passa quello attraverso jq per estrarre solo la voce che ti interessa:

# Esegui il controllo completo, output JSON, poi filtra a un file
shopify theme check -o json \
  | jq '.[] | select(.path == "sections/hero.liquid")'

Puoi anche asserire un codice di uscita diverso da zero tu stesso in base al risultato filtrato:

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 ha $ERRORS errore(i)"
  exit 1
fi

Questo pattern ti dà l'equivalente di gating per file nel tuo job GitHub Actions o GitLab CI, senza aver bisogno di un flag che non esiste.

Metodo 3: Pattern ignore in .theme-check.yml

Se l'obiettivo è silenziare un file o una cartella specifica piuttosto che sceglierla, .theme-check.yml supporta elenchi ignore basati su glob per ogni controllo. Puoi anche ignorare intere directory da tutti i controlli usando la chiave ignore di livello superiore:

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

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

Genera una configurazione iniziale con:

shopify theme check --init

Questo è particolarmente utile quando hai file generati o di terze parti (come snippet Replo) che contengono Liquid intenzionalmente diviso che altrimenti attiverebbe LiquidHTMLParsingError su theme dev.

Metodo 4: Commenti di soppressione inline all'interno di sections Liquid

Per regole una tantum all'interno di un file sezione specifico, i commenti Liquid inline ti permettono di disabilitare e riabilitare qualsiasi controllo denominato attorno a un blocco di codice:

{%- comment -%} Sopprimi falso positivo dal pattern di render del vendor {%- endcomment -%}
{% # theme-check-disable UnusedAssign %}
{%- assign hero_context = section.settings.context -%}
{% # theme-check-enable UnusedAssign %}

Puoi anche sopprimere un controllo per l'intero file mettendo il commento di disabilitazione sulla prima riga:

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

Questo approccio è visibile nella revisione del codice (appare come un diff a una riga) e non influisce su nessun altro file nel tema.

Metodo 5: onlySingleFileChecks di VS Code per lo sviluppo locale

Se il tuo obiettivo è un feedback veloce nel tuo editor mentre stai attivamente modificando un file sezione, l'estensione Shopify Liquid per VS Code ha un'impostazione che limita Theme Check solo al file aperto:

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

Con questo attivo, i controlli multifile (come MissingSnippet) vengono saltati e solo le regole di un singolo file vengono eseguite sulla scheda attiva. Il repository ufficiale lo descrive come "ottimo per le prestazioni se puoi ignorare i controlli che si estendono su più file durante lo sviluppo". Esegui il completo shopify theme check in CI per catturare i problemi multifile.

Confronto: ogni metodo affiancato

Requisiti di CLI 4.0 che non devi trascurare (maggio 2026)

Dall'uscita di CLI 4.0 nel maggio 2026, due requisiti sono cambiati e influenzano ogni pipeline CI che esegue Theme Check:

• Node 22.12+ è richiesto. Le versioni precedenti di Node falliranno silenziosamente o produrranno output imprevisti.
• Lo strumento si auto-aggiorna tramite il tuo package manager e salta l'auto-aggiornamento dentro CI per design. Fissa la tua versione in package.json o nella tua immagine CI esplicitamente.

Vale anche la pena sapere: --category e --exclude-category sono stati rimossi in Theme Check 2.x (gennaio 2024). Se trovi tutorial più vecchi che mostrano quei flag, non funzionano più. Usa -C theme-check:all per eseguire ogni controllo disponibile esplicitamente.

Pattern di gating CI: il modo giusto di eseguire Theme Check in una pipeline

Ecco la sequenza di pipeline idiomatica consigliata dalla documentazione di Shopify stesso:

# 1. Gating su errori (e avvertimenti, che la maggior parte dei team ignora per impostazione predefinita)
shopify theme check --fail-level warning

# 2. Spingi a un tema di sviluppo non pubblicato per l'anteprima
shopify theme push --unpublished --json

# 3. Promuovi solo dopo revisione manuale
shopify theme publish --theme <ID> --force

Due errori comuni da evitare:

• Il --fail-level predefinito è error, il che significa che gli avvertimenti si accumulano silenziosamente e il tuo job CI esce comunque con 0. Passa --fail-level warning per bloccare su di essi.
• --strict su theme push blocca anche il push a meno che Theme Check non passi, il che ti dà una seconda rete di sicurezza al momento del deploy.

Per i temi di anteprima per PR, shopify theme push --development-context "pr-482" lega un tema di sviluppo a un identificatore stabile come un numero di PR.

Mettendolo insieme: il flusso di lavoro pratico per sections Liquid

Ecco la sequenza su cui la maggior parte dei team finisce dopo aver passato attraverso quanto sopra:

1. Editor: abilita onlySingleFileChecks in VS Code per feedback veloce dentro il file mentre scrivi section Liquid.
2. Hook pre-commit: esegui shopify theme check --fail-level error contro l'intero tema prima che un commit vada su.
3. Gating pull request CI: esegui shopify theme check -o json | jq per estrarre e asserire solo sui file sezione modificati.
4. Gating deploy CI: esegui shopify theme push --strict così anche se qualcuno bypassa il passo 3, un push con errori è bloccato.
5. Config: mantieni un .theme-check.yml con glob ignore mirati per qualsiasi snippet generato o vendor per prevenire falsi positivi dal bloccare il lavoro vero.

Hai bisogno di aiuto per collegare questo a una pipeline vera? La pagina dei servizi sviluppatore tema Shopify ha contesto su come lo configuro per i progetti dei client, e Shopify speed optimization copre i controlli di performance che Theme Check segnala più spesso.