Vercel CLI with Tokens（トークン認証付き）
vercel loginに依存せず、CLIを使ってトークンベースの認証でVercel上のプロジェクトをデプロイ・管理します。
ステップ 1: Vercel トークンを特定する
Vercel CLIコマンドを実行する前に、トークンの取得元を特定します。以下のシナリオを順に確認してください。
A) 環境に VERCEL_TOKEN がすでに設定されている
printenv VERCEL_TOKEN
値が返ってきたら準備完了です。ステップ2に進んでください。
B) トークンが .env ファイル内の VERCEL_TOKEN にある
grep '^VERCEL_TOKEN=' .env 2>/dev/null
見つかった場合はエクスポートします：
export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)
C) トークンが .env ファイル内の別の変数名にある
Vercelトークン（通常 vca_ で始まる）のように見える変数を探します：
grep -i 'vercel' .env 2>/dev/null
出力を確認し、どの変数がトークンを保持しているか特定して、VERCEL_TOKEN としてエクスポートします：
export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-)
D) トークンが見つからない — ユーザーに問い合わせる
上記のいずれでもトークンが得られない場合、ユーザーにトークンの提供を依頼してください。ユーザーは vercel.com/account/tokens でVercelアクセストークンを作成できます。
重要: VERCEL_TOKEN が環境変数としてエクスポートされると、Vercel CLIはそれをネイティブに読み取ります — --token フラグとして渡さないでください。コマンドライン引数にシークレットを配置すると、シェル履歴やプロセス一覧に露出してしまいます。
# 悪い例 — トークンがシェル履歴やプロセス一覧に表示される
vercel deploy --token "vca_abc123"
# 良い例 — CLIが VERCEL_TOKEN を環境から読み取る
export VERCEL_TOKEN="vca_abc123"
vercel deploy
ステップ 2: プロジェクトとチームを特定する
同様に、プロジェクトIDとチームスコープを確認します。これにより、vercel link を必要とせずにCLIが正しいプロジェクトを対象にできます。
# 環境を確認
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID
# または .env を確認
grep -i 'vercel' .env 2>/dev/null
プロジェクトURLがある場合（例: https://vercel.com/my-team/my-project）、チームスラッグを抽出します：
# 例: "https://vercel.com/my-team/my-project" から "my-team"
echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1
環境に VERCEL_ORG_ID と VERCEL_PROJECT_ID の両方がある場合、それらをエクスポートします — CLIはこれらを自動的に使用し、.vercel/ ディレクトリをスキップします：
export VERCEL_ORG_ID="<org-id>"
export VERCEL_PROJECT_ID="<project-id>"
注: VERCEL_ORG_ID と VERCEL_PROJECT_ID は必ず一緒に設定してください — 片方だけ設定するとエラーになります。
CLI セットアップ
Vercel CLIがインストールされ、最新であることを確認します：
npm install -g vercel
vercel --version
プロジェクトのデプロイ
ユーザーが明示的に本番を要求しない限り、常にプレビューとしてデプロイします。利用可能なものに応じて方法を選択してください。
クイックデプロイ（プロジェクトIDがある場合 — リンク不要）
環境に VERCEL_TOKEN と VERCEL_PROJECT_ID が設定されている場合、直接デプロイします：
vercel deploy -y --no-wait
チームスコープを使用する場合（VERCEL_ORG_ID または --scope 経由）：
vercel deploy --scope <team-slug> -y --no-wait
本番（明示的に要求された場合のみ）：
vercel deploy --prod --scope <team-slug> -y --no-wait
ステータスを確認：
vercel inspect <deployment-url>
完全なデプロイフロー（プロジェクトIDがない場合 — リンクが必要）
トークンとチームはあるが、既存のプロジェクトIDがない場合に使用します。
最初にプロジェクトの状態を確認
# プロジェクトに git リモートがあるか？
git remote get-url origin 2>/dev/null
# すでにVercelプロジェクトにリンクされているか？
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
プロジェクトをリンク
git リモートがある場合（推奨）：
vercel link --repo --scope <team-slug> -y
git リモートを読み取り、一致するVercelプロジェクトに接続します。.vercel/repo.json を作成します。ディレクトリ名で一致する単純な vercel link より信頼性が高くなります。
git リモートがない場合：
vercel link --scope <team-slug> -y
.vercel/project.json を作成します。
特定のプロジェクト名にリンク：
vercel link --project <project-name> --scope <team-slug> -y
プロジェクトがすでにリンクされている場合、.vercel/project.json または .vercel/repo.json の orgId をチェックして、意図したチームと一致することを確認します。
リンク後にデプロイ
A) Git Push デプロイ — git リモートがある場合（推奨）
Gitプッシュによって自動的にVercelデプロイがトリガーされます。
- プッシュ前にユーザーに確認してください。 明示的な承認なしにプッシュしないでください。
- コミットしてプッシュ：
git add . git commit -m "deploy: <変更内容の説明>" git push - Vercelが自動的にビルドします。非本番ブランチはプレビューデプロイメントになります。
- デプロイURLを取得：
sleep 5 vercel ls --format json --scope <team-slug>deployments配列から最新のエントリを見つけます。
B) CLI デプロイ — git リモートがない場合
vercel deploy --scope <team-slug> -y --no-wait
ステータスを確認：
vercel inspect <deployment-url>
リモートリポジトリからのデプロイ（コードがローカルにクローンされていない場合）
- リポジトリをクローン：
git clone <repo-url> cd <repo-name> - Vercelにリンク：
vercel link --repo --scope <team-slug> -y - git push（プッシュアクセスがある場合）またはCLIデプロイでデプロイします。
.vercel/ ディレクトリについて
リンクされたプロジェクトには次のいずれかがあります：
.vercel/project.json—vercel linkによる。projectIdとorgIdを含む。.vercel/repo.json—vercel link --repoによる。orgId、remoteName、およびprojectsマップを含む。
VERCEL_ORG_ID + VERCEL_PROJECT_ID の両方が環境に設定されている場合は不要です。
リンクされていないディレクトリで vercel project inspect や vercel link を実行して状態を検出しないでください。 インタラクティブにプロンプトが表示されたり、副作用としてリンクが行われたりします。vercel ls は安全です（リンクされていないディレクトリでは、デフォルトでスコープのすべてのデプロイメントが表示されます）。vercel whoami はどこでも安全です。
環境変数の管理
# 全環境に設定
エコー "値" | vercel env add VAR_NAME --scope <team-slug>
# 特定の環境に設定（production、preview、development）
エコー "値" | vercel env add VAR_NAME production --scope <team-slug>
# 環境変数の一覧表示
vercel env ls --scope <team-slug>
# 環境変数をローカルの .env.local ファイルにプル
vercel env pull --scope <team-slug>
# 変数を削除
vercel env rm VAR_NAME --scope <team-slug> -y
デプロイメントの検査
# 最近のデプロイメントを一覧表示
vercel ls --format json --scope <team-slug>
# 特定のデプロイメントを検査
vercel inspect <deployment-url>
# ビルドログを表示（Vercel CLI v35+ が必要）
vercel inspect <deployment-url> --logs
# ランタイムリクエストログを表示（デフォルトでライブフォロー、--no-follow でスナップショット）
vercel logs <deployment-url>
ドメインの管理
# ドメインを一覧表示
vercel domains ls --scope <team-slug>
# プロジェクトにドメインを追加 — リンク済みまたは環境リンク済みディレクトリ（引数1つ）
vercel domains add <domain> --scope <team-slug>
# ドメインを追加 — リンクされていないディレクトリ（<project> 位置引数が必要）
vercel domains add <domain> <project> --scope <team-slug>
Stripe Projects プラン変更
このプロジェクトが Stripe Projects によって管理されている場合。有料または破壊的なプラン変更を実行する前にはユーザーに確認してください — アップグレードでは実際のカードに請求が発生し、ダウングレードではシートが削除されます。
最初に stripe projects status --json を実行して、Vercelリソースのローカル名を確認します。以下の例ではデフォルト（vercel-plan）を想定しています。stripe projects add 時にリネームされている場合は、実際の名前に置き換えてください。
- Pro にアップグレード:
stripe projects add vercel/pro（またはstripe projects upgrade vercel-plan pro） - Hobby にダウングレード:
stripe projects downgrade vercel-plan hobby
Pro で得られるもの
- 月額 $20 のプラットフォーム料金、月額 $20 の使用クレジット込み。
- 新規プロジェクトでデフォルトで Turbo ビルドマシン（30 vCPU、60 GB メモリ） — Hobby より大幅に高速なビルド。
- 1 デプロイシート + 無制限の無料 Viewer シート（読み取り専用コラボレーター、プレビューコメント）。
- より高い割り当て（月 1 TB の Fast Data Transfer、月 10M Edge Requests）。
- 有料アドオン利用可能：SAML SSO、HIPAA BAA、Flags Explorer、Observability Plus、Speed Insights、Web Analytics Plus。
詳細: https://vercel.com/docs/plans/pro-plan
作業合意事項
VERCEL_TOKENを--tokenフラグとして絶対に渡さないでください。 環境変数としてエクスポートし、CLIにネイティブに読み取らせてください。- ユーザーに問い合わせる前に、環境内のトークンを確認してください。 最初に現在の環境と
.envファイルを調べてください。 - デフォルトでプレビューデプロイメントにしてください。 明示的に要求された場合のみ本番にデプロイしてください。
- git にプッシュする前に確認してください。 ユーザーの承認なしにコミットをプッシュしないでください。
.vercel/ファイルを直接変更しないでください。 CLIがこのディレクトリを管理します。読み取り（例：orgIdの確認）は問題ありません。- デプロイされたURLを curl/fetch で確認しないでください。 リンクをユーザーに返すだけで構いません。
- 構造化された出力が後続のステップに役立つ場合、
--format jsonを使用してください。 - 確認を促すコマンドでは
-yを使用して、インタラクティブなブロックを避けてください。
トラブルシューティング
トークンが見つからない
環境と存在する .env ファイルを確認します：
printenv | grep -i vercel
grep -i vercel .env 2>/dev/null
認証エラー
CLIが Authentication required で失敗した場合：
- トークンが期限切れか無効である可能性があります。
- 確認:
vercel whoami（環境からVERCEL_TOKENを使用）。 - ユーザーに新しいトークンを依頼してください。
チームが間違っている
スコープが正しいことを確認します：
vercel whoami --scope <team-slug>
ビルド失敗
ビルドログを確認します：
vercel inspect <deployment-url> --logs
よくある原因：
- 依存関係が不足している —
package.jsonが完全でコミットされていることを確認してください。 - 環境変数が不足している —
vercel env addで追加してください。 - フレームワーク設定の誤り —
vercel.jsonを確認してください。Vercelはpackage.jsonからフレームワーク（Next.js、Remix、Vite など）を自動検出します。検出が間違っている場合はvercel.jsonで上書きしてください。
CLI がインストールされていない
npm install -g vercel