Shopify Theme Check File e Sezioni Specifiche con la CLI

Per eseguire Shopify Theme Check su file o sezioni specifici, hai tre opzioni: passare un argomento di percorso direttamente alla CLI, utilizzare commenti Liquid inline per disabilitare i controlli per blocchi di codice specifici, oppure configurare un pattern ignore nel tuo file .theme-check.yml. Non esiste un singolo flag --only che limita l'output a un file, ma combinando questi tre approcci ottieni un controllo preciso e mirato su cosa viene lintato e cosa viene saltato.

Punti chiave

• shopify theme check ./sections/hero.liquid limita l'esecuzione a un percorso file specifico.
• I commenti inline {% # theme-check-disable %} sopprimono i controlli per un blocco di codice Liquid denominato.
• .theme-check.yml ti consente di ignore per interi pattern glob (ad esempio, snippets/icon-*) in modo permanente.
• Il flag --config sostituisce il tuo file di configurazione al volo, utile nelle pipeline CI.
• La gem Ruby legacy Shopify/theme-check è stata archiviata a luglio 2024; il linter attuale vive dentro Shopify CLI attraverso i pacchetti @shopify/cli e @shopify/theme.

Perché il linting mirato è importante (e da dove viene la confusione)

Eseguire shopify theme check su un tema ampio con centinaia di file Liquid produce una marea di avvisi. La maggior parte degli sviluppatori vuole lintare solo il file su cui sta lavorando, o sopprimere un controllo rumoroso per una sezione senza disabilitarlo dappertutto. La documentazione della CLI risponde a questa domanda, ma è sparsa su tre pagine separate, ed è per questo che questa domanda continua a tornare.

La buona notizia: gli strumenti sono davvero flessibili. Una volta che sai quale leva tirare per quale caso d'uso, il flusso di lavoro è veloce.

Metodo 1: passa un percorso file come argomento posizionale

L'approccio più diretto. Invece di eseguire Theme Check sulla radice dell'intero tema, aggiungi il percorso relativo del file (o della directory) che vuoi controllare:

shopify theme check sections/custom-hero.liquid
shopify theme check snippets/product-card.liquid
shopify theme check sections/

Questo dice al linter di analizzare solo quel file o cartella. Un'avvertenza importante: i controlli di tema completi sono parzialmente soppressI quando limiti a un singolo file. I controlli che richiedono consapevolezza tra file, come UnusedSnippet o TranslationKeyExists, sono disabilitati in modalità file singolo perché hanno bisogno di leggere il tema completo per produrre un risultato significativo.

Per errori strettamente a livello di file (sintassi Liquid, filtri deprecati, oggetti non definiti, tag {% endschema %} mancanti), il limite a singolo file funziona perfettamente.

Metodo 2: sopprimere i controlli inline con commenti Liquid

Quando vuoi mantenere un ampio shopify theme check ma silenziare uno specifico controllo per una sezione di codice, usa le direttive di commento integrate di Theme Check:

{% # theme-check-disable UnusedAssign %}
{% assign debug_mode = true %}
{% # theme-check-enable UnusedAssign %}

Per disabilitare tutti i controlli per un blocco:

{% # theme-check-disable %}
  {# ...codice legacy che non hai ancora migrato... #}
{% # theme-check-enable %}

Questo approccio è la scelta giusta quando stai iterando su una sezione personalizzata complessa, ereditando una codebase di tema disordinata, o aggiungendo Theme Check a un progetto che ha un ampio backlog di problemi preesistenti che non sei pronto a risolvere in un'unica passata. I commenti sono strettamente limitati: nulla al di fuori di questi delimitatori è interessato.

Metodo 3: configura i pattern di ignore in .theme-check.yml

Per i percorsi che vuoi escludere permanentemente, il file di configurazione .theme-check.yml è lo strumento giusto. Puoi generare un file iniziale con:

shopify theme check --init

Quindi modifica il file per aggiungere globs ignore sotto controlli specifici o globalmente:

TemplateLength:
  enabled: true
  max_length: 400
  ignore:
    - sections/legacy-homepage.liquid
    - snippets/icon-*

Puoi anche impostare livelli di severità per controllo (error, warning, info) in modo che alcuni problemi facciano fallire un'esecuzione CI mentre altri vengono segnalati solo come informativi. Per impostazione predefinita, Theme Check restituisce il codice di uscita 1 quando almeno un problema con severità error viene rilevato. Usa --fail-level per regolare questa soglia per la tua pipeline:

shopify theme check --fail-level suggestion

Metodo 4: sostituisci la configurazione al volo con --config

Se mantieni più profili di controllo (uno rigoroso, uno permissivo), il flag --config ti permette di cambiare tra loro senza modificare alcun file:

shopify theme check --config theme-check:recommended
shopify theme check --config theme-check:all

Questi preset integrati coprono gli scenari più comuni. theme-check:recommended è il predefinito per la maggior parte degli invii di tema; theme-check:all abilita ogni controllo disponibile ed è utile per un audit approfondito prima della pubblicazione su Shopify Theme Store.

Cosa è cambiato nel 2024: archivio repo theme-check

Se hai segnalibri o tutorial più vecchi che fanno riferimento alla gem Ruby standalone Shopify/theme-check, nota che questo repository è stato archiviato in sola lettura a luglio 2024. Tutto lo sviluppo attivo si è spostato nel monorepo Shopify/theme-tools, e il linter è ora distribuito attraverso i pacchetti npm @shopify/cli e @shopify/theme.

Per installare o aggiornare:

# macOS
brew upgrade shopify-cli

# npm (globale)
npm install -g @shopify/cli @shopify/theme

A partire da Shopify CLI 4.0, la CLI si aggiorna automaticamente usando qualsiasi gestore di pacchetti con cui l'hai installata, quindi nella maggior parte dei casi sei già sulla versione più recente.

L'estensione VS Code (Shopify Liquid) aggrega anche Theme Check ed espone un'impostazione themeCheck.onlySingleFileChecks. Quando impostata su true, l'estensione controlla solo il file attualmente aperto, disabilitando i controlli di tema completo per le prestazioni. Questo rispecchia il comportamento del percorso file singolo della CLI ed è degno di nota su temi grandi dove il linting di tema completo ad ogni salvataggio rallenta l'editor.

Mettere tutto insieme: un flusso di lavoro pratico per lo sviluppo di sezioni

Ecco il pattern che funziona bene quando costruisci o esegui il debug di una sezione Liquid personalizzata:

1. Avvia un server di sviluppo: shopify theme dev --store your-store.myshopify.com
2. Modifica la tua sezione: apporta modifiche a sections/your-section.liquid
3. Lint solo quel file: shopify theme check sections/your-section.liquid
4. Sopprimere i controlli rumorosi inline per qualsiasi problema preesistente che non stai risolvendo oggi.
5. Esegui un controllo completo (shopify theme check) prima di aprire una richiesta pull o di eseguire il push in produzione.
6. Gated CI sugli errori solo usando --fail-level error in modo che gli avvisi non blocchino i deploy.

Questo approccio mantiene il tuo ciclo di feedback interno veloce mentre cattura comunque errori reali prima che raggiungano i clienti.

Mantenere il codice della vetrina pulito è uno strato dello stack operativo. L'altro strato è sapere, ogni singolo giorno, quali prodotti stanno per esaurirsi e cosa ti costa vendite reali. Se gestisci l'inventario su dozzine o centinaia di SKU, Stockcast: Inventory Forecast mette in superficie le previsioni di esaurimento ordinate per urgenza con una matematica trasparente e spiegabile dietro ogni raccomandazione, quindi le decisioni di riordine non sono mai una supposizione.

Prova Stockcast: Inventory Forecast su Shopify App Store

FAQ

Posso eseguire shopify theme check su un singolo file di sezione Liquid? Sì. Passa il percorso del file come argomento posizionale: shopify theme check sections/your-section.liquid. Nota che i controlli di tema completo (come il rilevamento di snippet non utilizzati) sono disabilitati quando limiti a un singolo file, poiché richiedono la lettura del tema completo per funzionare correttamente.

Come disabilito una specifica regola Theme Check per un blocco di codice senza disattivarla dappertutto? Usa le direttive di commento Liquid inline: {% # theme-check-disable CheckName %} prima del blocco e {% # theme-check-enable CheckName %} dopo. Questo sopprime solo quel controllo denominato all'interno del blocco delimitato e lascia il resto del file e del tema completamente lintato.

Cosa è successo alla gem/CLI theme-check standalone nel 2024? Shopify ha archiviato il repository della gem Ruby Shopify/theme-check a luglio 2024 e ha spostato tutto lo sviluppo attivo nel monorepo Shopify/theme-tools. Theme Check è ora distribuito come parte di @shopify/cli e viene eseguito tramite shopify theme check. Se sei in una configurazione più vecchia, aggiorna con brew upgrade shopify-cli o npm install -g @shopify/cli @shopify/theme.