Vercelへデプロイ は何をしますか?
任意のプロジェクトをVercelにデプロイします。常にプレビューとしてデプロイ(本番環境ではない)します。ただし、ユーザーが明示的に本番環境を要求した場合を除きます。
目標は、ユーザーを最適な長期的なセットアップ、つまりプロジェクトをVercelにリンクし、gitプッシュでデプロイできる状態に導くことです。以下のすべての方法は、ユーザーをその状態に近づけることを目指しています。
ステップ1: プロジェクトの状態を確認
デプロイ方法を決定する前に、以下の4つのチェックをすべて実行します。
# 1. gitリモートの確認
git remote get-url origin 2>/dev/null
# 2. ローカルでVercelプロジェクトにリンクされているか確認(いずれかのファイルが存在すればリンク済み)
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
# 3. Vercel CLIがインストールされ、認証されているか確認
vercel whoami 2>/dev/null
# 4. 利用可能なチームを表示(認証済みの場合)
vercel teams list --format json 2>/dev/null
チーム選択
ユーザーが複数のチームに所属している場合、利用可能なすべてのチームスラッグを箇条書きで表示し、どのチームにデプロイするか尋ねます。ユーザーがチームを選択したら、すぐに次のステップに進み、追加の確認は求めません。
以降のすべてのCLIコマンド(vercel deploy、vercel link、vercel inspectなど)には、チームスラッグを--scopeで渡します。
vercel deploy [path] -y --no-wait --scope <team-slug>
プロジェクトがすでにリンクされている場合(.vercel/project.jsonまたは.vercel/repo.jsonが存在する場合)、それらのファイル内のorgIdがチームを決定するため、再度尋ねる必要はありません。チームが1つだけ(または個人アカウントのみ)の場合は、プロンプトをスキップしてそのまま使用します。
.vercel/ディレクトリについて: リンクされたプロジェクトには、次のいずれかが存在します。
.vercel/project.json:vercel linkによって作成されます(単一プロジェクトのリンク)。projectIdとorgIdが含まれます。.vercel/repo.json:vercel link --repoによって作成されます(リポジトリベースのリンク)。orgId、remoteName、およびディレクトリをVercelプロジェクトIDにマッピングするprojects配列が含まれます。
どちらかのファイルが存在すれば、プロジェクトはリンクされています。両方を確認してください。
リンクされていないディレクトリで、.vercel/設定がない状態では、vercel project inspect、vercel ls、vercel linkを使用して状態を検出しないでください。 これらは対話的なプロンプトを表示するか(--yesを指定すると、副作用として静かにリンクします)。vercel whoamiだけはどこでも安全に実行できます。
ステップ2: デプロイ方法を選択
リンク済み(.vercel/が存在する)+ gitリモートあり → Git Push
これが理想的な状態です。プロジェクトがリンクされ、git統合が有効になっています。
-
プッシュする前にユーザーに確認します。 明示的な承認なしにプッシュしないでください。
このプロジェクトはgitを介してVercelに接続されています。コミットしてプッシュし、 デプロイをトリガーできます。続行しますか? -
コミットしてプッシュ:
git add . git commit -m "deploy: <変更の説明>" git pushVercelはプッシュから自動的にビルドします。本番ブランチ以外のブランチはプレビューデプロイメントを取得し、本番ブランチ(通常は
main)は本番デプロイメントを取得します。 -
プレビューURLを取得します。 CLIが認証されている場合:
sleep 5 vercel ls --format jsonJSON出力には
deployments配列があります。最新のエントリを見つけます。そのurlフィールドがプレビューURLです。CLIが認証されていない場合、ユーザーにVercelダッシュボードまたはgitプロバイダーのコミットステータスチェックでプレビューURLを確認するように伝えます。
リンク済み(.vercel/が存在する)+ gitリモートなし → vercel deploy
プロジェクトはリンクされていますが、gitリポジトリがありません。CLIで直接デプロイします。
vercel deploy [path] -y --no-wait
--no-waitを使用すると、ビルドが完了するのを待たずにCLIがすぐにデプロイメントURLを返します(ビルドには時間がかかる場合があります)。その後、次のコマンドでデプロイメントのステータスを確認します。
vercel inspect <deployment-url>
本番デプロイの場合(ユーザーが明示的に要求した場合のみ):
vercel deploy [path] --prod -y --no-wait
未リンク + CLI認証済み → リンクしてからデプロイ
CLIは動作していますが、プロジェクトがまだリンクされていません。これはユーザーを最適な状態に導くチャンスです。
-
どのチームにデプロイするかユーザーに尋ねます。 ステップ1のチームスラッグを箇条書きで表示します。チームが1つだけ(または個人アカウントのみ)の場合は、このステップをスキップします。
-
チームが選択されたら、すぐにリンクに進みます。 何が行われるかをユーザーに伝えますが、個別の確認は求めません。
このプロジェクトをVercelの<チーム名>にリンクしています。これにより、デプロイ先のVercelプロジェクトが作成され、 将来のgitプッシュで自動デプロイが有効になります。 -
gitリモートが存在する場合、選択したチームスコープでリポジトリベースのリンクを使用します。
vercel link --repo --scope <team-slug>これにより、gitリモートURLが読み取られ、そのリポジトリからデプロイする既存のVercelプロジェクトと照合されます。
.vercel/repo.jsonが作成されます。これは(--repoなしの)vercel linkよりもはるかに信頼性が高くなります。(--repoなしのvercel linkはディレクトリ名で一致を試みるため、ローカルフォルダとVercelプロジェクトの名前が異なる場合にしばしば失敗します。)gitリモートがない場合、標準のリンクにフォールバックします。
vercel link --scope <team-slug>これにより、ユーザーはプロジェクトを選択または作成するように求められます。
.vercel/project.jsonが作成されます。 -
次に、利用可能な最良の方法でデプロイします:
- gitリモートが存在する場合 → コミットしてプッシュ(上記のgit pushメソッドを参照)
- gitリモートがない場合 →
vercel deploy [path] -y --no-wait --scope <team-slug>、次にvercel inspect <url>でステータスを確認
未リンク + CLI未認証 → インストール、認証、リンク、デプロイ
Vercel CLIがまったくセットアップされていません。
-
CLIをインストールします(まだインストールされていない場合):
npm install -g vercel -
認証:
vercel loginユーザーはブラウザで認証を完了します。非対話型環境でログインが不可能な場合は、以下の認証不要のフォールバックにスキップします。
-
どのチームにデプロイするか尋ねます:
vercel teams list --format jsonからチームスラッグを箇条書きで表示します。チームが1つだけ/個人アカウントのみの場合はスキップします。選択されたら、すぐに進みます。 -
選択したチームスコープでプロジェクトをリンクします(gitリモートが存在する場合は
--repoを使用し、それ以外の場合は通常のvercel linkを使用):vercel link --repo --scope <team-slug> # gitリモートが存在する場合 vercel link --scope <team-slug> # gitリモートがない場合 -
利用可能な最良の方法でデプロイします(リモートが存在する場合はgit push、それ以外の場合は
vercel deploy -y --no-wait --scope <team-slug>、次にvercel inspect <url>でステータスを確認)。
認証不要のフォールバック、claude.aiサンドボックス
使用するタイミング: claude.aiサンドボックスでCLIをインストールまたは認証できない場合の最終手段です。認証は不要です。プレビューURL(ライブサイト)とクレームURL(自分のVercelアカウントに転送するため)を返します。
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [path]
引数:
path- デプロイするディレクトリ、または.tgzファイル(デフォルトはカレントディレクトリ)
例:
# カレントディレクトリをデプロイ
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh
# 特定のプロジェクトをデプロイ
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project
# 既存のtarballをデプロイ
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz
スクリプトはpackage.jsonからフレームワークを自動検出し、プロジェクトをパッケージ化し(node_modules、.git、.envを除外)、アップロードして、ビルドが完了するのを待ちます。
ユーザーに伝えます: 「デプロイが完了しました: [previewUrl]。クレームURL: [claimUrl] からデプロイを管理できます。」
認証不要のフォールバック。Codexサンドボックス
使用するタイミング: CodexサンドボックスでCLIが認証されていない可能性がある場合。Codexはデフォルトでサンドボックス環境で実行されるため、最初にCLIを試し、認証に失敗した場合はフォールバックスクリプトを使用します。
-
Vercel CLIがインストールされているか確認します(この確認に昇格は不要):
command -v vercel -
vercelがインストールされている場合、CLIでデプロイを試みます:vercel deploy [path] -y --no-wait -
vercelがインストールされていない場合、またはCLIが「No existing credentials found」で失敗した場合、フォールバックスクリプトを使用します:skill_dir="<skillへのパス>" # カレントディレクトリをデプロイ bash "$skill_dir/resources/deploy-codex.sh" # 特定のプロジェクトをデプロイ bash "$skill_dir/resources/deploy-codex.sh" /path/to/project # 既存のtarballをデプロイ bash "$skill_dir/resources/deploy-codex.sh" /path/to/project.tgz
スクリプトはフレームワークの検出、パッケージ化、デプロイを処理します。ビルドが完了するのを待ち、previewUrlとclaimUrlを含むJSONを返します。
ユーザーに伝えます: 「デプロイが完了しました: [previewUrl]。クレームURL: [claimUrl] からデプロイを管理できます。」
昇格したネットワークアクセス: サンドボックスがネットワーク呼び出しをブロックする場合のみ、実際のデプロイコマンドを昇格します(sandbox_permissions=require_escalated)。command -v vercelのチェックは昇格しないでください。
エージェント固有の注意事項
Claude Code / ターミナルベースのエージェント
シェルへのフルアクセスがあります。/mnt/skills/パスは使用しないでください。上記の決定フローに従い、CLIを直接使用します。
認証不要のフォールバックの場合は、スキルのインストール場所からデプロイスクリプトを実行します。
bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]
パスは、ユーザーがスキルをインストールした場所によって異なる場合があります。
サンドボックス環境(claude.ai)
vercel loginやgit pushはおそらく実行できません。直接認証不要のフォールバック、claude.aiサンドボックスに進みます。
Codex
Codexはサンドボックスで実行されます。最初にCLIが利用可能かどうかを確認し、利用できない場合はデプロイスクリプトにフォールバックします。認証不要のフォールバック。Codexサンドボックスに進みます。
出力
常にユーザーにデプロイメントURLを表示します。
- git push:
vercel ls --format jsonを使用してプレビューURLを見つけます。CLIが認証されていない場合は、Vercelダッシュボードまたはコミットステータスチェックを確認するようユーザーに伝えます。 - CLIデプロイ:
vercel deploy --no-waitによって返されたURLを表示します。vercel inspect <url>を使用してビルドステータスを確認し、ユーザーに報告します。 - 認証不要のフォールバック: プレビューURLとクレームURLの両方を表示します。
デプロイに成功しました! プレビューURL: https://my-app-abc123.vercel.app クレームURL: https://vercel.com/claim-deployment?code=... プレビューURLでサイトを表示できます。 このデプロイを自分のVercelアカウントに転送するには、クレームURLにアクセスしてください。
デプロイされたURLをcurlやfetchで確認して動作を検証しないでください。リンクを返すだけで構いません。
トラブルシューティング
ネットワークエグレスエラー(claude.ai)
claude.aiのネットワーク制限によりデプロイに失敗した場合は、ユーザーに次のように伝えます。
ネットワーク制限のためデプロイに失敗しました。修正するには:
1. https://claude.ai/settings/capabilities にアクセスします
2. 許可ドメインに *.vercel.com を追加します
3. 再度デプロイを試みます
昇格したネットワークアクセス(Codex / サンドボックス環境)
サンドボックス環境でネットワーク問題(タイムアウト、DNSエラー、接続リセット)によりデプロイに失敗した場合は、昇格した権限で再実行します(sandbox_permissions=require_escalated)。最初のCLI利用可能性チェックは昇格せず、実際のデプロイコマンドのみを昇格します。
ユーザーへのガイダンス例:
デプロイをVercelに実行するには、昇格したネットワークアクセスが必要です。
昇格した権限でコマンドを再実行できますが、続行しますか?
CLI認証エラー
vercel loginまたはvercel deployが認証エラーで失敗した場合は、認証不要のデプロイスクリプト(環境に応じてclaude.aiまたはCodexのバリアント)にフォールバックします。