mcloud-local

Cloud CLI：ローカルコマンド

mcloud local build を実行すると、Cloud がプロジェクトをビルドする方法を再現しながら、ローカルマシンで Cloud ビルドを実行できます。変更をプッシュして Cloud ビルド全体の完了を待つことなく、build-failed のデプロイをデバッグする際に使用します。

制約

• --json フラグは使用できません。 local build はビルド出力をプレーンテキストでストリーミングし、結果を 終了コード（0 = 成功）で通知します。出力を JSON として解析しないでください。
• **Docker がインストールされ、実行中である必要があります。**また、プロジェクトの Git リポジトリ内から実行する必要があります。
• 再現するのは build-failed（ビルド）の失敗のみで、deployment-failed（ランタイム）の失敗は対象外です。ランタイムの失敗には、mcloud logs --deployment <id> を使用してください。
• mcloud CLI v0.1.10 以降で利用できます。
• Docker ビルドキャッシュはデフォルトで無効になっているため、変数の変更は常にキャッシュを無効化します。有効にするには --docker-cache を渡してください。

コマンド

local build

Cloud ビルドをローカルで実行します。リンクされた Cloud プロジェクトと環境からルートパスとビルド変数を推定します。デフォルトではバックエンドをビルドします。ストアフロントをビルドするには --type storefront を渡してください。

mcloud local build \
  --organization <org-id> \
  --project <project-id-or-handle> \
  --environment <environment-handle>

オプション：

• -o/--organization <id> — 組織 ID（アクティブなコンテキストにフォールバックします）
• -p/--project <id-or-handle> — プロジェクト ID またはハンドル（アクティブなコンテキストにフォールバックします）
• -e/--environment <handle> — 変数を使用する環境（アクティブなコンテキストにフォールバックします）
• -t/--type <backend|storefront> — ビルドタイプ（デフォルト：backend）
• --root-path <path> — リポジトリルートからのバックエンドのルートパス（省略時は推定されます。Cloud プロジェクトが見つからない場合は .）
• --storefront-path <path> — --type storefront の場合に使用する、リポジトリルートからのストアフロントのパス（省略時は推定されます）
• --env-file <path> — Cloud 環境の変数の代わりに、ローカルの .env ファイルを使用します
• -v/--var <KEY=VALUE> — 単一のビルド変数を上書きします。繰り返し指定できます
• --docker-cache — Docker ビルドキャッシュを有効にします（デフォルト：false）

出力：

• 成功時（終了コード 0）、バックエンドイメージに <repository-name>:cloud-local-build-<commit-hash> というタグが付けられます。ストアフロントのビルドでは出力ディレクトリが作成され、そのパスが表示されます。
• 失敗時（終了コードが 0 以外）、コマンドは失敗したステップのエラーで終了します。Cloud ビルドと同じようにデバッグしてください。

ビルド失敗を再現する

ローカルビルドが同じ条件になるよう、失敗したデプロイでビルドされたコミットをチェックアウトしてから、終了コードに応じて処理します。

# Identify the failing deployment and the commit it built
DEPLOYMENT_ID=$(
  mcloud deployments list --json \
    | jq -r '[.[] | select(.backend_status == "build-failed")][0].id'
)
COMMIT=$(mcloud deployments get "$DEPLOYMENT_ID" --json | jq -r '.commit_hash')

git checkout "$COMMIT"

if mcloud local build; then
  echo "Build succeeded locally; failure not reproducible from this commit."
else
  echo "Build failed locally; inspect the streamed output for the failing step."
fi

ローカルビルドが終了コード 0 で終了したら、修正を追跡対象のブランチにプッシュし、mcloud environments trigger-build <env> で新しい Cloud ビルドを開始してください。

例

# Reproduce the backend build for the active context
mcloud local build

# Reproduce the storefront build
mcloud local build --type storefront --storefront-path apps/storefront

# Test a build-variable fix without editing code
mcloud local build --var NODE_ENV=production

# Build against a local .env file
mcloud local build --env-file .env

# Reuse the Docker cache for a faster rebuild
mcloud local build --docker-cache