Shopify Theme Check: 単一ファイルパス引数が機能しない理由(および代わりにすべきこと)

shopify theme check ./sections/header.liquidを実行しても役に立つことは何も起こりません。このコマンドは現在のCLIでは構文的に無効です。Theme Checkはポジショナルファイルパス引数を受け入れません。正しいスコープフラグは--pathで、ディレクトリのみを受け入れ、単一ファイルは受け入れません。ここで正確に何が機能するのか、単一ファイルのlintingがなぜ期待と異なるのか、そしてCIに適切に組み込む方法を説明します。

重要なポイント

• shopify theme check ./sections/header.liquidは現在のShopify CLIでは無効です。ポジショナルファイル引数はありません。
• --pathを使用してディレクトリを指定します(省略した場合は現在のワーキングディレクトリがデフォルト)。
• 真の単一ファイルフィードバックはVS Code Language Server(themeCheck.onlySingleFileChecks)からのみ得られ、CLIからではありません。
• デフォルトの--fail-levelはerrorなため、CIはサイレントに渡されて警告が蓄積します。常に--fail-level warningを渡してください。
• Shopify CLI 4.0(2026年5月)以降、Node 22.12+が必要で、CI外のパッケージマネージャーを通じて自動アップグレードされます。

ほとんどの開発者が犯す正確な間違い

sections/hero.liquidを編集していて、潜在的なlint問題を見つけて、次のように入力します。

shopify theme check ./sections/hero.liquid

役に立つことは何も起こりません。現在のCLIでは、そのポジショナル引数は単に無視されるか、テーマディレクトリが見つからないというエラーが発生します。

この混乱には特定の原因があります。Theme Check 2.x(Shopify CLIの内部に付属するNode ベースのバージョン)が古いRuby gemに置き換わったのですが、Ruby gemはパスのポジショナル引数を受け入れていました。Theme Check 2.xの移行前に書かれた古いチュートリアル、StackOverflowの回答、ブログ記事(2024年初頭に最終化、同時に--categoryと--exclude-categoryが削除されました)は、古い構文をまだ示しています。これらの記事は現在は誤っています。

Shopifyの公式CLIリファレンスで確認されているように、--pathがスコープを指定する唯一の方法で、ディレクトリに対してスコープされます。

このフラグが実際に何をするのか

# 特定のテーマディレクトリにスコープを設定
shopify theme check --path ./my-theme

# 現在のワーキングディレクトリをデフォルトにする
shopify theme check

# 修正可能な問題を自動修正
shopify theme check -a

# ゼロ以外の終了を引き起こす重要度レベルを変更
shopify theme check --fail-level warning

# マシンが読み取り可能な出力(ファイルごとのフラットアレイ)
shopify theme check -o json > results.json

# すべてのアクティブなチェックとその重要度をリスト表示
shopify theme check --list

--pathはTheme Checkにテーマルートとして扱うディレクトリを指示します。そのディレクトリ内のすべてのファイル(テンプレート、セクション、スニペット、レイアウト、アセット)は1回のパスでチェックされます。CLIレベルで単一ファイルに絞ることはできません。

実際に単一ファイルをlintする方法: Language Serverのアプローチ

CLIはテーマ全体のツールです。単一ファイルフィードバックはShopify Liquid Language Serverの役割で、これはShopify Liquid VS Code拡張機能に電力を供給します。

拡張機能はthemeCheck.onlySingleFileChecksという設定を公開しています。trueに設定すると、テーマ全体のチェック(UnusedSnippetやTranslationKeyExistsなど)が無効になり、エディタで現在開いているファイルのみをチェックします。これにより、textDocument/didChangeチェックが各キー入力でのテーマ全体の再チェックと比較して約125倍高速化されます。

VS Codeワークスペース設定に以下を追加します。

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

トレードオフ:コーディング中はクロスファイルチェックが漏れます。推奨パターンは、ローカルで速度のためにonlySingleFileChecks: trueを実行してから、プッシュ前にCIでテーマ全体に対して完全なshopify theme checkを実行することです。

比較: 単一ファイルフィードバックのためのCLI対Language Server

CIをサイレントに壊す--fail-levelの落とし穴

これはlintゲートを初めて設定するほぼすべてのチームを悩ませます。

デフォルトでは、--fail-levelはerrorに設定されています。つまり、警告のみを見つけた実行は終了コード0で終了します。CIジョブはそのエラーコードをチェックし、0を見て、ステップを緑色にマークし、これらの警告は数十のPRで静かに蓄積されます。最終的に誰かが非推奨フィルターやパフォーマンス問題に気付くまで、それは数ヶ月間本番環境に座っています。

1行で修正してください。

shopify theme check --fail-level warning

許可されるレベル(最も厳しいものから最も緩いものまで):

• info
• suggestion
• style
• warning
• error(デフォルト)
• crash

ほとんどのストアでは、warningが正しい閾値です。実際の問題をキャッチしますが、純粋にスタイル的なサジェストでブロックしません。

本番グレードのCIパターン(GitHub Actions)

以下は最小限の現在のパターンです。非対話的な認証にSHOPIFY_CLI_THEME_TOKENを使用し、任意のプッシュ前にTheme Checkでビルドをゲートします。

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

theme pushの--strictはTheme Checkエラーのみでブロックするため、--fail-level warningを専用チェックステップで渡すことが正しいゲートで、--strictのみに頼るのではありません。

知っておく価値のある3つのフラグ

• -a / --auto-correct: Theme Checkが人間の判断なしで解決できる違反を修正します(括弧の中のスペース{% %}、使用されていない割り当て)。ローカルで実行し、CIで盲目的に実行しません。
• --list: すべてのアクティブなチェックとその重要度を出力します。チームメンバーが.theme-check.ymlを追加し、リリース前にアクティブなルールセットを確認する場合に便利です。
• -C theme-check:all: theme-check:recommendedで無効になっているものを含むすべての利用可能なチェックを有効にします。定期的な深いオーディットに使用し、日次ゲートではありません。

CLI 4.0(2026年5月)で変更された内容があなたのセットアップに影響するもの

2026年5月以降、パイプラインが奇妙に動作し始めた場合、原因はShopify CLI 4.0の可能性があります。テーマチェック実行に影響する2つの変更がありました。

1. Node 22.12+が必須になりました。 Node 18または20にピンされたパイプラインはインストールステップで失敗します。
2. CI では自動アップグレードがスキップされます。 CLIはCI環境を検出せず、自動更新されません。これは正しい動作です。しかし、プロジェクトローカルのインストールも自動アップグレードをスキップするため、パイプラインが必要なバージョンを明示的にインストールすることを確認してください。

ボーナスとして、theme initはDawnの代わりにデフォルトでShopifyのSkeletonテーマをクローンしています。これはTheme Checkの動作には影響しませんが、同じパイプラインで新しいプロジェクトをスキャフォルディングしている場合は重要です。

一般的な.theme-check.ymlミス

テーマルートにある.theme-check.ymlファイルは、どのチェックを実行するか、どの重要度で実行するかを制御します。混乱を引き起こすいくつかのパターン:

# 正しい: 推奨から拡張し、上書きする
extend: theme-check:recommended

TemplateLength:
  enabled: false

UnusedAssign:
  severity: suggestion   # 警告からダウングレード

ParserBlockingJavaScript:
  enabled: true
  severity: error

• --categoryまたは--exclude-categoryを使用しないでください。これらのフラグはTheme Check 2.xで削除されました。代わりにYAMLファイルを使用してください。
• rootキーは、テーマファイルがサブディレクトリ(ビルド出力フォルダなどdist/)に存在する場合にのみ必要です。標準的なDawnまたはHorizonの構造には必要ありません。

Theme Checkが完全なShopifyテーマワークフローにどのように適合するかについて、より広い視点を得るには、Shopifyテーマ開発とLiquidベストプラクティスガイドを参照してください。

これをCI/CDパイプラインに組み込み、より大きな移行またはビルドシステムの一部として実行している場合、Shopifyテーマ開発者サービスページは、クライアントプロジェクトの自動化された品質ゲートへのアプローチをカバーします。