PhuongDeveloper/landingpage

Vercel CLI mit Tokens

Projekte auf Vercel mit der CLI und Token-basierter Authentifizierung bereitstellen und verwalten, ohne auf vercel login angewiesen zu sein.

Schritt 1: Das Vercel-Token finden

Bevor Sie Vercel CLI-Befehle ausführen, identifizieren Sie, woher das Token stammt. Gehen Sie nacheinander durch diese Szenarien:

A) VERCEL_TOKEN ist bereits in der Umgebung gesetzt

printenv VERCEL_TOKEN

Wenn dies einen Wert zurückgibt, sind Sie bereit. Fahren Sie mit Schritt 2 fort.

B) Token befindet sich in einer .env-Datei unter VERCEL_TOKEN

grep '^VERCEL_TOKEN=' .env 2>/dev/null

Wenn gefunden, exportieren Sie es:

export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)

C) Token befindet sich in einer .env-Datei unter einem anderen Namen

Suchen Sie nach einer Variablen, die wie ein Vercel-Token aussieht (Vercel-Tokens beginnen typischerweise mit vca_):

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

Überprüfen Sie die Ausgabe, um die Variable zu identifizieren, die das Token enthält, und exportieren Sie sie dann als VERCEL_TOKEN:

export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-)

D) Kein Token gefunden – Benutzer fragen

Wenn keines der obigen Verfahren ein Token liefert, bitten Sie den Benutzer, eines bereitzustellen. Sie können ein Vercel-Zugriffstoken unter vercel.com/account/tokens erstellen.

---

Wichtig: Sobald VERCEL_TOKEN als Umgebungsvariable exportiert wurde, liest die Vercel CLI es nativ – übergeben Sie es nicht als --token-Flag. Das Einfügen von Geheimnissen in Befehlszeilenargumente setzt sie der Shell-Historie und Prozesslisten aus.

# Schlecht – Token sichtbar in Shell-Historie und Prozesslisten
vercel deploy --token "vca_abc123"

# Gut – CLI liest VERCEL_TOKEN aus der Umgebung
export VERCEL_TOKEN="vca_abc123"
vercel deploy

Schritt 2: Projekt und Team finden

Überprüfen Sie analog die Projekt-ID und den Team-Bereich. Diese ermöglichen es der CLI, das richtige Projekt anzusprechen, ohne dass vercel link erforderlich ist.

# Umgebung prüfen
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID

# Oder .env prüfen
grep -i 'vercel' .env 2>/dev/null

Wenn Sie eine Projekt-URL haben (z.B. https://vercel.com/my-team/my-project), extrahieren Sie den Team-Slug:

# z.B. "my-team" aus "https://vercel.com/my-team/my-project"
echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1

Wenn sowohl VERCEL_ORG_ID als auch VERCEL_PROJECT_ID in Ihrer Umgebung vorhanden sind, exportieren Sie sie – die CLI verwendet diese automatisch und überspringt das .vercel/-Verzeichnis:

export VERCEL_ORG_ID="<org-id>"
export VERCEL_PROJECT_ID="<project-id>"

Hinweis: VERCEL_ORG_ID und VERCEL_PROJECT_ID müssen zusammen gesetzt werden – das Setzen nur einer führt zu einem Fehler.

CLI-Setup

Stellen Sie sicher, dass die Vercel CLI installiert und auf dem neuesten Stand ist:

npm install -g vercel
vercel --version

Ein Projekt bereitstellen

Stellen Sie immer als Preview bereit, es sei denn, der Benutzer fordert explizit die Produktion an. Wählen Sie eine Methode basierend auf dem, was Ihnen zur Verfügung steht.

Schnelles Bereitstellen (Projekt-ID vorhanden – kein Verknüpfen nötig)

Wenn VERCEL_TOKEN und VERCEL_PROJECT_ID in der Umgebung gesetzt sind, direkt bereitstellen:

vercel deploy -y --no-wait

Mit einem Team-Bereich (entweder via VERCEL_ORG_ID oder --scope):

vercel deploy --scope <team-slug> -y --no-wait

Produktion (nur auf ausdrückliche Anfrage):

vercel deploy --prod --scope <team-slug> -y --no-wait

Status prüfen:

vercel inspect <deployment-url>

Vollständiger Bereitstellungsablauf (keine Projekt-ID – Verknüpfen erforderlich)

Verwenden Sie dies, wenn Sie ein Token und ein Team, aber keine vorhandene Projekt-ID haben.

Projektstatus zuerst prüfen

# Hat das Projekt ein Git-Remote?
git remote get-url origin 2>/dev/null

# Ist es bereits mit einem Vercel-Projekt verknüpft?
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

Das Projekt verknüpfen

Mit Git-Remote (bevorzugt):

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

Liest das Git-Remote und verbindet sich mit dem passenden Vercel-Projekt. Erstellt .vercel/repo.json. Zuverlässiger als einfaches vercel link, das nach Verzeichnisnamen abgleicht.

Ohne Git-Remote:

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

Erstellt .vercel/project.json.

Mit einem bestimmten Projektnamen verknüpfen:

vercel link --project <project-name> --scope <team-slug> -y

Wenn das Projekt bereits verknüpft ist, überprüfen Sie orgId in .vercel/project.json oder .vercel/repo.json, um sicherzustellen, dass es dem beabsichtigten Team entspricht.

Nach dem Verknüpfen bereitstellen

A) Git-Push-Bereitstellung – Git-Remote vorhanden (bevorzugt)

Git-Pushes lösen automatische Vercel-Bereitstellungen aus.

1. Fragen Sie den Benutzer vor dem Pushen. Nie ohne ausdrückliche Genehmigung pushen.
2. Committen und pushen:

   git add .
   git commit -m "deploy: <Beschreibung der Änderungen>"
   git push
   

3. Vercel erstellt automatisch. Nicht-Produktions-Branches erhalten Preview-Bereitstellungen.
4. Die Bereitstellungs-URL abrufen:

   sleep 5
   vercel ls --format json --scope <team-slug>
   

   Den neuesten Eintrag im deployments-Array finden.

B) CLI-Bereitstellung – kein Git-Remote

vercel deploy --scope <team-slug> -y --no-wait

Status prüfen:

vercel inspect <deployment-url>

Von einem entfernten Repository bereitstellen (Code nicht lokal geklont)

1. Repository klonen:

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

2. Mit Vercel verknüpfen:

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

3. Per Git-Push bereitstellen (wenn Sie Push-Zugriff haben) oder per CLI.

Über das .vercel/-Verzeichnis

Ein verknüpftes Projekt hat entweder:

• .vercel/project.json – von vercel link. Enthält projectId und orgId.
• .vercel/repo.json – von vercel link --repo. Enthält orgId, remoteName und eine projects-Map.

Nicht erforderlich, wenn sowohl VERCEL_ORG_ID als auch VERCEL_PROJECT_ID in der Umgebung gesetzt sind.

Führen Sie vercel project inspect oder vercel link NICHT in einem nicht verknüpften Verzeichnis aus, um den Status zu ermitteln – sie werden interaktiv nachfragen oder als Nebeneffekt stillschweigend verknüpfen. vercel ls ist sicher (in einem nicht verknüpften Verzeichnis zeigt es standardmäßig alle Bereitstellungen für den Bereich an). vercel whoami ist überall sicher.

Umgebungsvariablen verwalten

# Für alle Umgebungen setzen
echo "Wert" | vercel env add VAR_NAME --scope <team-slug>

# Für eine bestimmte Umgebung setzen (production, preview, development)
echo "Wert" | vercel env add VAR_NAME production --scope <team-slug>

# Umgebungsvariablen auflisten
vercel env ls --scope <team-slug>

# Umgebungsvariablen in lokale .env.local-Datei ziehen
vercel env pull --scope <team-slug>

# Eine Variable entfernen
vercel env rm VAR_NAME --scope <team-slug> -y

Bereitstellungen inspizieren

# Kürzliche Bereitstellungen auflisten
vercel ls --format json --scope <team-slug>

# Eine bestimmte Bereitstellung inspizieren
vercel inspect <deployment-url>

# Build-Logs anzeigen (erfordert Vercel CLI v35+)
vercel inspect <deployment-url> --logs

# Laufzeit-Anfrage-Logs anzeigen (folgt live; mit --no-follow für einen einmaligen Snapshot)
vercel logs <deployment-url>

Domänen verwalten

# Domänen auflisten
vercel domains ls --scope <team-slug>

# Eine Domäne zum Projekt hinzufügen – verknüpftes oder env-verknüpftes Verzeichnis (1 Argument)
vercel domains add <domain> --scope <team-slug>

# Eine Domäne hinzufügen – nicht verknüpftes Verzeichnis (erfordert <project>-Position)
vercel domains add <domain> <project> --scope <team-slug>

Stripe-Projekte – Tarifänderungen

Wenn dieses Projekt von Stripe Projects verwaltet wird. Fragen Sie den Benutzer, bevor Sie kostenpflichtige oder destruktive Tarifänderungen vornehmen – Upgrades berechnen eine echte Kreditkarte, Downgrades entfernen Sitze.

Führen Sie zuerst stripe projects status --json aus, um den lokalen Namen der Vercel-Ressource zu bestätigen. Die folgenden Beispiele gehen vom Standard (vercel-plan) aus; ersetzen Sie den tatsächlichen Namen, falls er bei stripe projects add umbenannt wurde.

• Upgrade auf Pro: stripe projects add vercel/pro (oder stripe projects upgrade vercel-plan pro)
• Downgrade auf Hobby: stripe projects downgrade vercel-plan hobby

Was Pro bietet

• 20 $/Monat Plattformgebühr, beinhaltet 20 $/Monat Nutzungsguthaben.
• Turbo-Build-Maschinen (30 vCPUs, 60 GB Arbeitsspeicher) standardmäßig für neue Projekte – deutlich schnellere Builds als Hobby.
• 1 bereitstellender Sitzplatz + unbegrenzte kostenlose Viewer-Sitze (schreibgeschützte Mitarbeiter, Vorschau-Kommentare).
• Höhere enthaltene Zuteilungen (1 TB Fast Data Transfer, 10M Edge Requests pro Monat).
• Kostenpflichtige Add-ons verfügbar: SAML SSO, HIPAA BAA, Flags Explorer, Observability Plus, Speed Insights, Web Analytics Plus.

Vollständige Details: https://vercel.com/docs/plans/pro-plan

Arbeitsvereinbarung

• Übergeben Sie VERCEL_TOKEN niemals als --token-Flag. Exportieren Sie es als Umgebungsvariable und lassen Sie die CLI es nativ lesen.
• Überprüfen Sie die Umgebung auf Tokens, bevor Sie den Benutzer fragen. Suchen Sie zuerst in der aktuellen Umgebung und .env-Dateien.
• Standardmäßig Preview-Bereitstellungen verwenden. Nur auf ausdrückliche Anfrage in der Produktion bereitstellen.
• Vor Git-Push fragen. Nie Commits ohne Zustimmung des Benutzers pushen.
• .vercel/-Dateien nicht direkt ändern. Die CLI verwaltet dieses Verzeichnis. Sie zu lesen (z.B. zur Überprüfung von orgId) ist in Ordnung.
• Bereitgestellte URLs nicht mit curl/fetch überprüfen. Geben Sie einfach den Link an den Benutzer zurück.
• --format json verwenden, wenn strukturierte Ausgabe bei Folgeschritten hilft.
• -y verwenden bei Befehlen, die nach einer Bestätigung fragen, um interaktive Blockaden zu vermeiden.

Fehlerbehebung

Token nicht gefunden

Überprüfen Sie die Umgebung und alle vorhandenen .env-Dateien:

printenv | grep -i vercel
grep -i vercel .env 2>/dev/null

Authentifizierungsfehler

Wenn die CLI mit Authentication required fehlschlägt:

• Das Token ist möglicherweise abgelaufen oder ungültig.
• Überprüfen: vercel whoami (verwendet VERCEL_TOKEN aus der Umgebung).
• Bitten Sie den Benutzer um ein neues Token.

Falsches Team

Überprüfen Sie, ob der Bereich korrekt ist:

vercel whoami --scope <team-slug>

Build-Fehler

Überprüfen Sie die Build-Logs:

vercel inspect <deployment-url> --logs

Häufige Ursachen:

• Fehlende Abhängigkeiten – stellen Sie sicher, dass package.json vollständig und committet ist.
• Fehlende Umgebungsvariablen – mit vercel env add hinzufügen.
• Falsche Framework-Konfiguration – prüfen Sie vercel.json. Vercel erkennt Frameworks (Next.js, Remix, Vite usw.) automatisch aus package.json; überschreiben Sie die Erkennung mit vercel.json, falls sie falsch ist.

CLI nicht installiert

npm install -g vercel