Auf Vercel bereitstellen
Stellen Sie jedes Projekt auf Vercel bereit. Immer als Vorschau bereitstellen (nicht Produktion), es sei denn, der Benutzer fordert explizit die Produktion an.
Das Ziel ist, den Benutzer in die beste langfristige Einrichtung zu bringen: sein Projekt mit Vercel verknüpft und mit Git-Push-Bereitstellungen. Jede untenstehende Methode versucht, den Benutzer diesem Zustand näher zu bringen.
Schritt 1: Projektstatus erfassen
Führen Sie alle vier Prüfungen durch, bevor Sie sich für eine Methode entscheiden:
# 1. Nach einem Git-Remote suchen
git remote get-url origin 2>/dev/null
# 2. Prüfen, ob lokal mit einem Vercel-Projekt verknüpft (entweder Datei bedeutet verknüpft)
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
# 3. Prüfen, ob die Vercel-CLI installiert und authentifiziert ist
vercel whoami 2>/dev/null
# 4. Verfügbare Teams auflisten (wenn authentifiziert)
vercel teams list --format json 2>/dev/null
Teamauswahl
Wenn der Benutzer zu mehreren Teams gehört, präsentieren Sie alle verfügbaren Team-Slugs als Aufzählungsliste und fragen Sie, auf welches bereitgestellt werden soll. Sobald der Benutzer ein Team ausgewählt hat, fahren Sie sofort mit dem nächsten Schritt fort, ohne zusätzliche Bestätigung zu verlangen.
Übergeben Sie den Team-Slug über --scope bei allen nachfolgenden CLI-Befehlen (vercel deploy, vercel link, vercel inspect usw.):
vercel deploy [pfad] -y --no-wait --scope <team-slug>
Wenn das Projekt bereits verknüpft ist (.vercel/project.json oder .vercel/repo.json existiert), bestimmt die orgId in diesen Dateien das Team, es ist nicht nötig, erneut zu fragen. Wenn es nur ein Team (oder nur ein persönliches Konto) gibt, überspringen Sie die Eingabeaufforderung und verwenden Sie es direkt.
Über das .vercel/-Verzeichnis: Ein verknüpftes Projekt hat entweder:
.vercel/project.json: erstellt vonvercel link(Einzelprojektverknüpfung). EnthältprojectIdundorgId..vercel/repo.json: erstellt vonvercel link --repo(Repo-basierte Verknüpfung). EnthältorgId,remoteNameund einprojects-Array, das Verzeichnisse Vercel-Projekt-IDs zuordnet.
Jede dieser Dateien bedeutet, dass das Projekt verknüpft ist. Prüfen Sie beide.
Verwenden Sie NICHT vercel project inspect, vercel ls oder vercel link, um den Status in einem nicht verknüpften Verzeichnis zu erkennen, ohne eine .vercel/-Konfiguration. Diese werden interaktiv nachfragen (oder mit --yes stillschweigend als Nebeneffekt verknüpfen). Nur vercel whoami kann sicher überall ausgeführt werden.
Schritt 2: Bereitstellungsmethode auswählen
Verknüpft (.vercel/ existiert) + hat Git-Remote → Git Push
Dies ist der ideale Zustand. Das Projekt ist verknüpft und hat Git-Integration.
-
Fragen Sie den Benutzer vor dem Pushen. Niemals ohne explizite Zustimmung pushen:
Dieses Projekt ist über Git mit Vercel verbunden. Ich kann committen und pushen, um eine Bereitstellung auszulösen. Möchten Sie fortfahren? -
Committen und pushen:
git add . git commit -m "deploy: <Beschreibung der Änderungen>" git pushVercel baut automatisch aus dem Push. Nicht-Produktions-Branches erhalten Vorschau-Bereitstellungen; der Produktions-Branch (normalerweise
main) erhält eine Produktions-Bereitstellung. -
Die Vorschau-URL abrufen. Wenn die CLI authentifiziert ist:
sleep 5 vercel ls --format jsonDie JSON-Ausgabe hat ein
deployments-Array. Finden Sie den neuesten Eintrag. Seinurl-Feld ist die Vorschau-URL.Wenn die CLI nicht authentifiziert ist, teilen Sie dem Benutzer mit, dass er die Vorschau-URL im Vercel-Dashboard oder in den Commit-Statusprüfungen seines Git-Anbieters überprüfen soll.
Verknüpft (.vercel/ existiert) + kein Git-Remote → vercel deploy
Das Projekt ist verknüpft, aber es gibt kein Git-Repo. Direkt mit der CLI bereitstellen.
vercel deploy [pfad] -y --no-wait
Verwenden Sie --no-wait, damit die CLI sofort mit der Bereitstellungs-URL zurückkehrt, anstatt zu blockieren, bis der Build abgeschlossen ist (Builds können eine Weile dauern). Überprüfen Sie dann den Bereitstellungsstatus mit:
vercel inspect <deployment-url>
Für Produktions-Bereitstellungen (nur wenn der Benutzer explizit danach fragt):
vercel deploy [pfad] --prod -y --no-wait
Nicht verknüpft + CLI ist authentifiziert → Zuerst verknüpfen, dann bereitstellen
Die CLI funktioniert, aber das Projekt ist noch nicht verknüpft. Dies ist die Gelegenheit, den Benutzer in den besten Zustand zu bringen.
-
Fragen Sie den Benutzer, auf welches Team bereitgestellt werden soll. Präsentieren Sie die Team-Slugs aus Schritt 1 als Aufzählungsliste. Wenn es nur ein Team (oder nur ein persönliches Konto) gibt, überspringen Sie diesen Schritt.
-
Sobald ein Team ausgewählt ist, fahren Sie direkt mit der Verknüpfung fort. Teilen Sie dem Benutzer mit, was passieren wird, aber verlangen Sie keine separate Bestätigung:
Dieses Projekt wird mit <Teamname> auf Vercel verknüpft. Dadurch wird ein Vercel-Projekt für die Bereitstellung erstellt und automatische Bereitstellungen bei zukünftigen Git-Pushes aktiviert. -
Wenn ein Git-Remote existiert, verwenden Sie die Repo-basierte Verknüpfung mit dem ausgewählten Team-Scope:
vercel link --repo --scope <team-slug>Dies liest die Git-Remote-URL und gleicht sie mit vorhandenen Vercel-Projekten ab, die von diesem Repo aus bereitstellen. Es erstellt
.vercel/repo.json. Dies ist viel zuverlässiger alsvercel link(ohne--repo), das versucht, nach Verzeichnisnamen abzugleichen und oft fehlschlägt, wenn der lokale Ordner und das Vercel-Projekt unterschiedlich benannt sind.Wenn kein Git-Remote vorhanden ist, fallen Sie auf die Standardverknüpfung zurück:
vercel link --scope <team-slug>Dies fordert den Benutzer auf, ein Projekt auszuwählen oder zu erstellen. Es erstellt
.vercel/project.json. -
Dann mit der besten verfügbaren Methode bereitstellen:
- Wenn ein Git-Remote existiert → committen und pushen (siehe Git-Push-Methode oben)
- Wenn kein Git-Remote →
vercel deploy [pfad] -y --no-wait --scope <team-slug>, dannvercel inspect <url>zum Überprüfen des Status
Nicht verknüpft + CLI nicht authentifiziert → Installieren, authentifizieren, verknüpfen, bereitstellen
Die Vercel-CLI ist überhaupt nicht eingerichtet.
-
CLI installieren (falls noch nicht geschehen):
npm install -g vercel -
Authentifizieren:
vercel loginDer Benutzer schließt die Authentifizierung in seinem Browser ab. Wenn Sie in einer nicht-interaktiven Umgebung arbeiten, in der eine Anmeldung nicht möglich ist, fahren Sie mit dem Authentifizierungsfreien Fallback unten fort.
-
Fragen Sie, auf welches Team bereitgestellt werden soll: Präsentieren Sie die Team-Slugs aus
vercel teams list --format jsonals Aufzählungsliste. Wenn nur ein Team / persönliches Konto vorhanden ist, überspringen Sie diesen Schritt. Sobald ausgewählt, fahren Sie sofort fort. -
Projekt verknüpfen mit dem ausgewählten Team-Scope (
--repoverwenden, wenn ein Git-Remote existiert, ansonsten einfachesvercel link):vercel link --repo --scope <team-slug> # wenn Git-Remote existiert vercel link --scope <team-slug> # wenn kein Git-Remote -
Bereitstellen mit der besten verfügbaren Methode (Git Push, wenn Remote existiert, ansonsten
vercel deploy -y --no-wait --scope <team-slug>, dannvercel inspect <url>zum Überprüfen des Status).
Authentifizierungsfreier Fallback, claude.ai Sandbox
Wann verwenden: Als letztes Mittel, wenn die CLI in der claude.ai-Sandbox nicht installiert oder authentifiziert werden kann. Dies erfordert keine Authentifizierung. Es gibt eine Vorschau-URL (Live-Site) und eine Claim-URL (Übertragung auf Ihr Vercel-Konto) zurück.
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [pfad]
Argumente:
pfad- Zu deployendes Verzeichnis oder eine.tgz-Datei (standardmäßig aktuelles Verzeichnis)
Beispiele:
# Aktuelles Verzeichnis bereitstellen
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh
# Bestimmtes Projekt bereitstellen
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /pfad/zum/projekt
# Vorhandenes Tarball bereitstellen
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /pfad/zum/projekt.tgz
Das Skript erkennt automatisch das Framework aus der package.json, packt das Projekt (ohne node_modules, .git, .env), lädt es hoch und wartet, bis der Build abgeschlossen ist.
Teilen Sie dem Benutzer mit: „Ihre Bereitstellung ist bereit unter [previewUrl]. Beanspruchen Sie sie unter [claimUrl], um Ihre Bereitstellung zu verwalten.“
Authentifizierungsfreier Fallback. Codex-Sandbox
Wann verwenden: In der Codex-Sandbox, in der die CLI möglicherweise nicht authentifiziert ist. Codex läuft standardmäßig in einer Sandbox-Umgebung; versuchen Sie es zuerst mit der CLI und fallen Sie auf das Bereitstellungsskript zurück, wenn die Authentifizierung fehlschlägt.
-
Prüfen, ob die Vercel-CLI installiert ist (keine Eskalation für diese Prüfung erforderlich):
command -v vercel -
Wenn
vercelinstalliert ist, versuchen Sie, mit der CLI bereitzustellen:vercel deploy [pfad] -y --no-wait -
Wenn
vercelnicht installiert ist oder die CLI mit „Keine vorhandenen Anmeldeinformationen gefunden“ fehlschlägt, verwenden Sie das Fallback-Skript:skill_dir="<pfad-zum-skill>" # Aktuelles Verzeichnis bereitstellen bash "$skill_dir/resources/deploy-codex.sh" # Bestimmtes Projekt bereitstellen bash "$skill_dir/resources/deploy-codex.sh" /pfad/zum/projekt # Vorhandenes Tarball bereitstellen bash "$skill_dir/resources/deploy-codex.sh" /pfad/zum/projekt.tgz
Das Skript übernimmt die Framework-Erkennung, Paketerstellung und Bereitstellung. Es wartet auf den Abschluss des Builds und gibt JSON mit previewUrl und claimUrl zurück.
Teilen Sie dem Benutzer mit: „Ihre Bereitstellung ist bereit unter [previewUrl]. Beanspruchen Sie sie unter [claimUrl], um Ihre Bereitstellung zu verwalten.“
Eskalierter Netzwerkzugriff: Eskalieren Sie nur den tatsächlichen Bereitstellungsbefehl, wenn die Sandbox den Netzwerkaufruf blockiert (sandbox_permissions=require_escalated). Eskalieren Sie NICHT die command -v vercel-Prüfung.
Agentspezifische Hinweise
Claude Code / terminalbasierte Agenten
Sie haben vollen Shell-Zugriff. Verwenden Sie NICHT den /mnt/skills/-Pfad. Folgen Sie dem obigen Entscheidungsfluss direkt mit der CLI.
Für den authentifizierungsfreien Fallback führen Sie das Bereitstellungsskript vom installierten Speicherort des Skills aus:
bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [pfad]
Der Pfad kann variieren, je nachdem, wo der Benutzer den Skill installiert hat.
Sandbox-Umgebungen (claude.ai)
Sie können wahrscheinlich weder vercel login noch git push ausführen. Gehen Sie direkt zum authentifizierungsfreien Fallback, claude.ai-Sandbox.
Codex
Codex läuft in einer Sandbox. Prüfen Sie zuerst, ob die CLI verfügbar ist, und fallen Sie dann auf das Bereitstellungsskript zurück. Gehen Sie zum authentifizierungsfreien Fallback. Codex-Sandbox.
Ausgabe
Zeigen Sie dem Benutzer immer die Bereitstellungs-URL.
- Git Push: Verwenden Sie
vercel ls --format json, um die Vorschau-URL zu finden. Wenn die CLI nicht authentifiziert ist, teilen Sie dem Benutzer mit, dass er das Vercel-Dashboard oder die Commit-Statusprüfungen überprüfen soll. - CLI-Bereitstellung: Zeigen Sie die von
vercel deploy --no-waitzurückgegebene URL. Verwenden Sievercel inspect <url>, um den Build-Status zu überprüfen und dem Benutzer zu melden. - Authentifizierungsfreier Fallback: Zeigen Sie sowohl die Vorschau-URL als auch die Claim-URL:
Bereitstellung erfolgreich! Vorschau-URL: https://my-app-abc123.vercel.app Claim-URL: https://vercel.com/claim-deployment?code=... Zeigen Sie Ihre Seite unter der Vorschau-URL an. Um diese Bereitstellung auf Ihr Vercel-Konto zu übertragen, besuchen Sie die Claim-URL.
Verwenden Sie NICHT curl oder fetch, um die bereitgestellte URL zu überprüfen. Geben Sie einfach den Link zurück.
Fehlerbehebung
Netzwerk-Egress-Fehler (claude.ai)
Wenn die Bereitstellung aufgrund von Netzwerkbeschränkungen auf claude.ai fehlschlägt, teilen Sie dem Benutzer mit:
Bereitstellung aufgrund von Netzwerkbeschränkungen fehlgeschlagen. Zur Behebung:
1. Gehen Sie zu https://claude.ai/settings/capabilities
2. Fügen Sie *.vercel.com zu den erlaubten Domains hinzu
3. Versuchen Sie die Bereitstellung erneut
Eskalierter Netzwerkzugriff (Codex / Sandbox-Umgebungen)
Wenn die Bereitstellung aufgrund von Netzwerkproblemen (Timeouts, DNS-Fehler, Verbindungsabbrüche) in einer Sandbox-Umgebung fehlschlägt, führen Sie sie mit eskalierten Berechtigungen erneut aus (sandbox_permissions=require_escalated). Eskalieren Sie nicht die anfängliche CLI-Verfügbarkeitsprüfung, sondern nur den tatsächlichen Bereitstellungsbefehl.
Beispielhinweis an den Benutzer:
Die Bereitstellung benötigt eskalierten Netzwerkzugriff, um auf Vercel bereitzustellen.
Ich kann den Befehl mit eskalierten Berechtigungen erneut ausführen. Möchten Sie fortfahren?
CLI-Authentifizierungsfehler
Wenn vercel login oder vercel deploy mit Authentifizierungsfehlern fehlschlägt, fallen Sie auf das authentifizierungsfreie Bereitstellungsskript zurück (claude.ai- oder Codex-Variante, je nach Umgebung).