vercel-cli-with-tokens

トークンを使用した Vercel CLI

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 トークンらしい変数を探します（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 フラグで渡さないでください。 シークレットをコマンドライン引数に含めると、シェルの履歴やプロセス一覧に露出してしまいます。

# Bad — token visible in shell history and process listings
vercel deploy --token "vca_abc123"

# Good — CLI reads VERCEL_TOKEN from the environment
export VERCEL_TOKEN="vca_abc123"
vercel deploy

ステップ 2: プロジェクトとチームを確認する

同様に、プロジェクト ID とチームスコープを確認します。これらを設定すると、vercel link を使わずに CLI が対象のプロジェクトを特定できます。

# Check environment
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID

# Or check .env
grep -i 'vercel' .env 2>/dev/null

プロジェクト URL がある場合（例: https://vercel.com/my-team/my-project）は、チームのスラッグを抽出します。

# e.g. "my-team" from "https://vercel.com/my-team/my-project"
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 がない場合に使用します。

最初にプロジェクトの状態を確認する

# Does the project have a git remote?
git remote get-url origin 2>/dev/null

# Is it already linked to a Vercel project?
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 プッシュによるデプロイ — Git リモートがある場合（推奨）

Git へのプッシュにより、Vercel のデプロイが自動的に開始されます。

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

   git add .
   git commit -m "deploy: <description of changes>"
   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 プッシュ（プッシュ権限がある場合）または 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 はどこで実行しても安全です。

環境変数の管理

# Set for all environments
echo "value" | vercel env add VAR_NAME --scope <team-slug>

# Set for a specific environment (production, preview, development)
echo "value" | vercel env add VAR_NAME production --scope <team-slug>

# List environment variables
vercel env ls --scope <team-slug>

# Pull env vars to local .env.local file
vercel env pull --scope <team-slug>

# Remove a variable
vercel env rm VAR_NAME --scope <team-slug> -y

デプロイメントの確認

# List recent deployments
vercel ls --format json --scope <team-slug>

# Inspect a specific deployment
vercel inspect <deployment-url>

# View build logs (requires Vercel CLI v35+)
vercel inspect <deployment-url> --logs

# View runtime request logs (follows live by default; add --no-follow for a one-shot snapshot)
vercel logs <deployment-url>

ドメインの管理

# List domains
vercel domains ls --scope <team-slug>

# Add a domain to the project — linked or env-linked directory (1 arg)
vercel domains add <domain> --scope <team-slug>

# Add a domain — unlinked directory (requires <project> positional)
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、1,000 万回の 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