Shopify Theme Check: Perché un singolo argomento di percorso file non funziona (e cosa fare invece)

Eseguire shopify theme check ./sections/header.liquid non produce risultati utili. Il comando è sintatticamente non valido sulla CLI attuale: Theme Check non accetta un argomento di percorso file posizionale. Il flag di ambito corretto è --path, e accetta solo una directory, non un singolo file. Ecco esattamente cosa funziona, perché il linting di un singolo file funziona diversamente da quello che ti aspetti, e come collegarlo correttamente a CI.

Punti chiave

• shopify theme check ./sections/header.liquid è non valido sulla CLI Shopify attuale. Non ci sono argomenti di file posizionali.
• Usa --path per indicare una directory (per impostazione predefinita la directory di lavoro corrente se omesso).
• I veri feedback single-file provengono dal Language Server VS Code (themeCheck.onlySingleFileChecks), non dalla CLI.
• Il valore predefinito di --fail-level è error, quindi CI passa silenziosamente mentre gli avvisi si accumulano. Passa sempre --fail-level warning.
• A partire da Shopify CLI 4.0 (maggio 2026), lo strumento richiede Node 22.12+ e si aggiorna automaticamente tramite il tuo package manager al di fuori di CI.

L'errore esatto che commettono la maggior parte degli sviluppatori

Stai modificando sections/hero.liquid, noti un potenziale problema di lint, e digiti:

shopify theme check ./sections/hero.liquid

Non succede nulla di utile. Sulla CLI attuale, quell'argomento posizionale viene semplicemente ignorato o produce un errore sulla directory tema mancante.

Questa confusione ha una causa specifica: Theme Check 2.x (la versione basata su Node fornita all'interno di Shopify CLI) ha sostituito la gem Ruby più vecchia, e la gem Ruby accettava un argomento di percorso posizionale. Tutorial più vecchi, risposte su StackOverflow e post di blog scritti prima della migrazione di Theme Check 2.x (finalizzata all'inizio del 2024, con --category e --exclude-category rimossi contemporaneamente) mostrano ancora la sintassi vecchia. Questi post sono sbagliati ora.

Come confermato dallo stesso riferimento CLI di Shopify, --path è l'unico modo per scoped una run, e scoped a una directory, non a un file.

Cosa il flag effettivamente fa

# Limita a una directory tema specifica
shopify theme check --path ./my-theme

# Per impostazione predefinita, la directory di lavoro corrente
shopify theme check

# Corregge automaticamente le violazioni risolvibili
shopify theme check -a

# Cambia quale livello di gravità causa un'uscita diversa da zero
shopify theme check --fail-level warning

# Output leggibile dalla macchina (array piatto per file)
shopify theme check -o json > results.json

# Elenca ogni controllo attivo e la sua gravità
shopify theme check --list

--path dice a Theme Check quale directory trattare come root tema. Ogni file all'interno di quella directory (template, sezioni, snippet, layout, asset) viene verificato in una sola passata. Non puoi limitarlo a un singolo file a livello CLI.

Come effettivamente eseguire il lint di un singolo file: l'approccio Language Server

La CLI è uno strumento per tema completo. Il feedback single-file è il lavoro del Shopify Liquid Language Server, che alimenta l'estensione Shopify Liquid per VS Code.

L'estensione espone un'impostazione chiamata themeCheck.onlySingleFileChecks. Quando impostata a true, disabilita i controlli di tema intero (come UnusedSnippet e TranslationKeyExists) e controlla solo i file attualmente aperti nell'editor. Questo fa sì che i controlli textDocument/didChange si eseguano circa 125 volte più velocemente rispetto ai re-check di tema completo ad ogni pressione di tasto.

Aggiungi questo alle impostazioni dell'area di lavoro VS Code:

{
  "themeCheck.checkOnOpen": true,
  "themeCheck.checkOnChange": true,
  "themeCheck.checkOnSave": true,
  "themeCheck.onlySingleFileChecks": true
}

Il compromesso: perderai i controlli cross-file mentre codifichi. Lo schema consigliato è eseguire onlySingleFileChecks: true localmente per velocità, quindi eseguire il shopify theme check completo su tutto il tema in CI prima di qualsiasi push.

Confronto: CLI vs Language Server per feedback single-file

L'inganno --fail-level che rompe silenziosamente CI

Questo confonde quasi ogni team che configura un gate di lint per la prima volta.

Per impostazione predefinita, --fail-level è impostato a error. Questo significa che una run che trova solo avvisi esce con codice 0. Il tuo lavoro CI controlla il codice di uscita, vede 0, contrassegna il passaggio in verde, e questi avvisi si accumulano silenziosamente in dozzine di PR finché qualcuno non nota finalmente un filtro deprecato o un odore di prestazioni che è rimasto in produzione per mesi.

Risolvilo in una riga:

shopify theme check --fail-level warning

Livelli accettati, dal più al meno rigoroso:

• info
• suggestion
• style
• warning
• error (predefinito)
• crash

Per la maggior parte dei negozi, warning è la soglia corretta. Cattura i problemi reali senza bloccare su suggerimenti puramente stilistici.

Un pattern CI di qualità produzione (GitHub Actions)

Di seguito è riportato il pattern minimo e attuale. Utilizza SHOPIFY_CLI_THEME_TOKEN per l'autenticazione non interattiva e limita il build su Theme Check prima di qualsiasi push.

name: Theme Lint and Deploy
on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        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 -o json > tc-results.json
        env:
          SHOPIFY_FLAG_STORE: ${{ secrets.SHOPIFY_STORE }}

      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: theme-check-results
          path: tc-results.json

  deploy:
    needs: lint
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Install Shopify CLI
        run: npm install -g @shopify/cli @shopify/theme
      - name: Push theme
        run: shopify theme push --json --theme ${{ secrets.SHOPIFY_THEME_ID }}
        env:
          SHOPIFY_CLI_THEME_TOKEN: ${{ secrets.SHOPIFY_CLI_THEME_TOKEN }}
          SHOPIFY_FLAG_STORE: ${{ secrets.SHOPIFY_STORE }}

Nota che --strict su theme push blocca solo gli errori di Theme Check, quindi passare --fail-level warning nel passaggio di controllo dedicato è il gate corretto, non affidarsi solo a --strict.

Tre altri flag che vale la pena conoscere

• -a / --auto-correct: risolve le violazioni che Theme Check può risolvere senza giudizio umano (spaziatura dentro {% %}, assign inutilizzati). Esegui questo localmente, mai ciecamente in CI.
• --list: stampa ogni controllo abilitato e la sua gravità. Utile quando un membro del team aggiunge un .theme-check.yml e desideri verificare il set di regole attive prima di un rilascio.
• -C theme-check:all: abilita ogni controllo disponibile, inclusi quelli disabilitati in theme-check:recommended. Usa questo per un audit profondo periodico, non come gate quotidiano.

Cosa è cambiato in CLI 4.0 (maggio 2026) che influisce sulla tua configurazione

Se la tua pipeline ha iniziato a comportarsi stranamente dopo maggio 2026, la causa è probabilmente Shopify CLI 4.0. Due cose sono cambiate che influiscono sulle run di theme check:

1. Node 22.12+ è ora richiesto. Le pipeline fissate a Node 18 o 20 falliranno al passaggio di installazione.
2. L'auto-upgrade è saltato in CI. La CLI rileva gli ambienti CI e non si auto-aggiorna, che è il comportamento corretto. Ma gli install locali del progetto saltano anche l'auto-upgrade, quindi assicurati che la tua pipeline installi esplicitamente la versione che desideri.

Come bonus, theme init ora clona il tema Skeleton di Shopify per impostazione predefinita invece di Dawn. Questo non influisce sul comportamento di Theme Check, ma importa se stai scaffolding un nuovo progetto nella stessa pipeline.

Errori comuni di .theme-check.yml

Il tuo file .theme-check.yml si trova alla root tema e controlla quali controlli vengono eseguiti e con quale gravità. Alcuni pattern che causano confusione:

# Corretto: estendi da recommended, poi sovrascrivi
extend: theme-check:recommended

TemplateLength:
  enabled: false

UnusedAssign:
  severity: suggestion   # downgrade da warning

ParserBlockingJavaScript:
  enabled: true
  severity: error

• Non usare --category o --exclude-category. Questi flag sono stati rimossi in Theme Check 2.x. Usa invece il file YAML.
• La chiave root è necessaria solo quando i tuoi file tema si trovano in una sottodirectory (ad es. una cartella di output build come dist/). Non ne hai bisogno per una struttura standard Dawn o Horizon.

Per un'occhiata più ampia a come Theme Check si adatta a un flusso di lavoro tema Shopify completo, vedi la mia guida alle best practice per lo sviluppo di temi Shopify e Liquid.

Se stai collegando questo a una pipeline CI/CD come parte di una migrazione più ampia o di un sistema di build, la pagina del servizio sviluppatore tema Shopify copre come affrontiamo i gate di qualità automatizzati sui progetti client.