Vercel CLI トークン管理

トークンを使った Vercel CLI

Vercel CLI をトークンベースの認証で使用し、vercel login に頼らずにプロジェクトのデプロイと管理を行います。

ステップ 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 アクセストークン（vercel.com/account/tokens で作成可能）の入力を依頼してください。

---

重要: 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 の自動デプロイがトリガーされます。

1. プッシュ前にユーザーに確認を取ること。 明示的な承認なしにプッシュしないでください。
2. コミットしてプッシュ:

   git add .
   git commit -m "deploy: <変更内容の説明>"
   git push
   

3. Vercel が自動的にビルドします。プロダクション以外のブランチはプレビューデプロイメントになります。
4. デプロイメント 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>

リモートリポジトリからのデプロイ（コードがローカルにクローンされていない場合）

1. リポジトリをクローン:

   git clone <repo-url>
   cd <repo-name>
   

2. Vercel にリンク:

   vercel link --repo --scope <team-slug> -y
   

3. 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 はどこでも安全です。

環境変数の管理

# すべての環境に設定
echo "value" | vercel env add VAR_NAME --scope <team-slug>

# 特定の環境（production、preview、development）に設定
echo "value" | 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

# ランタイムリクエストログを表示（デフォルトでライブフォロー; 1回限りのスナップショットは --no-follow を追加）
vercel logs <deployment-url>

ドメインの管理

# ドメインの一覧表示
vercel domains ls --scope <team-slug>

# プロジェクトにドメインを追加 — リンク済みまたは env リンク済みディレクトリ（引数 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 の高速データ転送、1000 万 Edge リクエスト）。
• 有料アドオンが利用可能: 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