shopify theme check --path vs 位置指定引数: 決定版シンタックスガイド

shopify theme check --path ./your-theme を使用してリント実行をディレクトリにスコープします。現在の Shopify CLI には位置指定引数がありません。shopify theme check ./sections/header.liquid は無効なシンタックスであり、CLI はそのファイルをリントしません。--path フラグは、ツールがディレクトリスコープ指定のために公開している唯一のメカニズムです。

重要なポイント

• --path は実行をディレクトリにスコープします。単一のファイルパスを受け付けません。
• 位置指定引数 (例: shopify theme check ./sections/header.liquid) はサポートされていませんし、有用な出力を生成しません。
• --path を省略すると、デフォルトで現在の作業ディレクトリになります。
• SHOPIFY_FLAG_PATH 環境変数は --path の CI 相当です。
• CLI 4.0 (2026年5月リリース) 以降、Node 22.12+ と Git 2.28+ が必須です。

コアの混乱: なぜコマンドがファイルを受け付けるように見えるのか

他のすべての一般的なリンター (ESLint, Stylelint, RuboCop) は位置指定ファイルまたはグロブを受け付けます。

eslint src/main.js          # 有効
stylelint "src/**/*.css"    # 有効
shopify theme check ./sections/header.liquid  # 無効

Shopify Theme Check はこの規約に従いません。CLI の theme check コマンドは位置指定引数を一切受け付けません。パスを位置指定引数として渡した場合、CLI はエラーを大きく出さず、単に無視して現在の作業ディレクトリをリントします。このサイレント フォールバックがこのバグを見つけにくくしているのです。

これは見た目以上に重要です。1つのノイジーなファイルをデバッグしている開発者は、shopify theme check ./snippets/icon-sprite.liquid を実行し、全テーマレポートを見て、そのファイルのチェックに合格したと仮定し、出荷します。チェックは独立して実行されていません。

--path フラグ: 実際に何をするのか

--path フラグは Theme Check にテーマルートとして使用するディレクトリを指定します。省略時は現在の作業ディレクトリにデフォルト設定されます。

# 現在のディレクトリのテーマをリント (暗黙的)
shopify theme check

# サブディレクトリのテーマをリント
shopify theme check --path ./my-theme

# ビルド出力フォルダーのテーマをリント
shopify theme check --path ./dist

重要: --path は標準的な Shopify テーマフォルダー構造 (templates/, sections/, snippets/ など) を含むディレクトリを指す必要があります。単一のファイルパスを渡すのも有効ではありません。

環境変数の相当は SHOPIFY_FLAG_PATH で、現在の CLI でほぼすべての他のフラグが使用する標準的な SHOPIFY_FLAG_* 命名パターンに従います。

shopify theme check の完全なフラグリファレンス

以下は、実際に使用するすべてのフラグとその目的です。

--fail-level フラグは CI パイプラインに特に重要です。デフォルトでは、Theme Check は error 重大度の問題でのみコード 1 で終了します。警告もブロックしたい場合は、明示的に指定する必要があります。

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

CLI で単一ファイルをリントできない理由

Theme Check は全テーマリンターとして設計されており、ファイルリンターではありません。多くのチェックはファイル間のコンテキストに依存します。

• UnusedSnippet は {% render %} を呼び出すすべてのファイルを知る必要があります。
• TranslationKeyExists は Liquid とともにロケールファイルを読む必要があります。
• MissingTemplate は参照をチェックするために完全な templates/ ディレクトリが必要です。

単一ファイルチェックを実行すると、これらのファイル間ルールについて無意味な結果が生成されます。これは見落としではなく、意図的な設計決定です。入力時にファイルごとのフィードバックが必要な場合は、Shopify Liquid VS Code 拡張機能を使用してください。これは Theme Check の言語サーバープロトコル (LSP) をリアルタイムで実行します。

これはTheme Check 2.0 がリリースされたとき、リンターを統一し、LSP 機能 (設定、翻訳、HTML、Liquid のホバードキュメントとコード補完) をエディター内に直接追加するという大きな前進でした。

CLI 4.0 (2026年5月) で何が変わったか

古いチュートリアルを実行している場合は、2026年5月にリリースされた Shopify CLI 4.0 が、theme check の実行方法に影響する複数の変更を導入したことに注意してください。

• デフォルトで自動アップグレード: CLI はパッケージマネージャー経由で自動的に自動アップグレードされます。自動アップグレードは CI 環境およびメジャーバージョンバンプではスキップされます。
• Node 22.12+ と Git 2.28+ が必須。 以前の Node バージョンはインストール時にエラーがスローされます。
• theme init は Dawn ではなく Skeleton をクローン。 これは新しいビルドのためにスキャフォールドされるテーマ構造に影響します。
• インタラクティブログインコマンドなし: 現在の CLI には shopify login や shopify whoami がありません。認証はトークンベースです。

CI/CD パイプラインについては、記載されている非インタラクティブパターンは依然としてリンターゲートの後にプッシュします。

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

CI での Theme Check のスコープ指定: 正しい方法

最小限ですが本番対応の GitHub Actions ステップを示します。

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

Shopify の公式 theme-check-action@v2 を使用する場合、パスの相当は位置指定引数ではなく theme_root 入力です。

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

theme_root 入力は内部的に --path にマップされます。flags 入力を使用すると、--fail-level を含む追加フラグを渡すことができます。

3つのアプローチを比較

チェック全体を無効にせずに誤検知を抑制

Theme Check が有効なコード (カスタム Liquid フィルター、サードパーティタグ) にフラグを立てた場合は、チェック全体をグローバルに無効にするのではなく、インライン抑制コメントを使用します。

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

複数のファイル全体の永続的な誤検知の場合、.theme-check.yml の ignore キーがよりクリーンです。

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

shopify theme check --init でいつでもスターター設定を生成できます。これは Shopify の推奨設定で事前にロードされた .theme-check.yml を作成します。

環境変数の優先度チェーン

現在の CLI での優先度は以下の通りです: フラグ > 環境変数 > shopify.theme.toml。コマンドラインの --path フラグは環境の SHOPIFY_FLAG_PATH をオーバーライドし、これは toml ファイルに設定されたパスをオーバーライドします。スクリプト内の迷いがあるインラインフラグは CI 環境変数を無視し、これは「ローカルでは動作するが CI では動作しない」という混乱の一般的な原因です。

CI ステップが引き続き対話的にプロンプトを表示している場合は、SHOPIFY_FLAG_FORCE=1 を追加して確認プロンプトを抑制します。

プロフェッショナルなテーマ開発ワークフローがどのように組み合わさるのかについてさらに深く理解するには、Shopify テーマ開発 Liquid ベストプラクティスガイドを参照してください。テーマのフロントエンドパフォーマンスをリント同時に最適化している場合は、Shopify スピード最適化は補完的なランタイム側をカバーします。